Protected Paths

Protected Paths#

Protected paths allow you to make specific files or directories read-only within writable context paths, preventing agents from modifying or deleting critical reference files while allowing them to edit other files.

Note

Use Case: You want agents to modify some files in a directory but keep certain reference files, configurations, or templates untouched.

Quick Start#

Protect a single file:

orchestrator:
  context_paths:
    - path: "/path/to/project"
      permission: "write"
      protected_paths:
        - "config.json"  # Agents can read but not modify

Example usage:

massgen \
  --config @examples/tools/filesystem/gemini_gpt5nano_protected_paths.yaml \
  "Review the HTML and CSS files, then improve the styling"

What Are Protected Paths?#

Protected paths are files or directories within a writable context path that are explicitly marked as read-only. Agents can:

  • ✅ Read protected files for reference

  • ✅ Write/Edit non-protected files in the same directory

  • ❌ Modify or Delete protected files

This gives you fine-grained control over what agents can change.

Why Use Protected Paths?#

Without protected paths:

❌ Context path: /project (write permission)
   → Agents can modify ALL files including critical configs

With protected paths:

✅ Context path: /project (write permission)
   ├── config.json (protected - read only)
   ├── template.html (protected - read only)
   └── styles.css (writable)
   → Agents can only modify styles.css

Configuration#

Basic Configuration#

Protect specific files within a writable context path:

orchestrator:
  context_paths:
    - path: "/absolute/path/to/directory"
      permission: "write"
      protected_paths:
        - "important_file.txt"
        - "config.json"

Result:

  • Agents can read and modify all files except important_file.txt and config.json

  • Protected files are readable but not writable

Multiple Protected Paths#

Protect multiple files or directories:

orchestrator:
  context_paths:
    - path: "/project"
      permission: "write"
      protected_paths:
        - "README.md"              # File protection
        - "docs/"                  # Directory protection
        - ".github/workflows/"     # Protect CI/CD configs
        - "package.json"           # Protect dependencies

Relative Path Syntax#

Protected paths are relative to the context path:

orchestrator:
  context_paths:
    - path: "/Users/me/project"
      permission: "write"
      protected_paths:
        - "src/config.py"          # Protects /Users/me/project/src/config.py
        - "tests/fixtures/"        # Protects /Users/me/project/tests/fixtures/

Complete Example#

Realistic configuration for a web project:

agents:
  - id: "frontend_agent"
    backend:
      type: "claude_code"
      cwd: "workspace"

  - id: "reviewer_agent"
    backend:
      type: "gemini"
      model: "gemini-2.5-flash"

orchestrator:
  snapshot_storage: "snapshots"
  agent_temporary_workspace: "temp_workspaces"
  context_paths:
    - path: "/Users/me/website"
      permission: "write"
      protected_paths:
        - "index.html"           # Keep original structure
        - "assets/logo.png"      # Don't modify brand assets
        - ".git/"                # Never touch version control
        # styles.css is NOT protected - agents can modify it

ui:
  display_type: "rich_terminal"

Usage:

massgen \
  --config website_config.yaml \
  "Improve the CSS styling while keeping the HTML structure intact"

Result:

  • ✅ Agents can read index.html for structure understanding

  • ✅ Agents can freely modify styles.css

  • ❌ Agents cannot change index.html or assets/logo.png

Use Cases#

Use Case 1: Protect Reference Files#

Scenario: Let agents improve code while keeping test fixtures unchanged.

context_paths:
  - path: "/project"
    permission: "write"
    protected_paths:
      - "tests/fixtures/"
      - "tests/expected_outputs/"

Task: “Refactor the parser module to improve performance”

Result: Agents can modify parser code but test fixtures remain untouched for validation.

Use Case 2: Protect Configuration#

Scenario: Allow code changes but prevent config file modifications.

context_paths:
  - path: "/app"
    permission: "write"
    protected_paths:
      - "config.yaml"
      - ".env.example"
      - "docker-compose.yml"

Task: “Add error handling to the API endpoints”

Result: Agents improve code without accidentally changing deployment configs.

Use Case 3: Protect Templates#

Scenario: Let agents generate content based on templates without modifying the templates.

context_paths:
  - path: "/website"
    permission: "write"
    protected_paths:
      - "templates/"
      - "layouts/"

Task: “Generate blog posts using the templates”

Result: Agents create new content files without touching template structure.

Use Case 4: Protect Documentation Structure#

Scenario: Allow content updates but preserve documentation organization.

context_paths:
  - path: "/docs"
    permission: "write"
    protected_paths:
      - "index.md"              # Keep main page structure
      - "_sidebar.md"           # Preserve navigation
      - "_config.yml"           # Don't change doc settings

Task: “Update the API reference documentation”

Result: Agents update specific doc pages without reorganizing the documentation structure.

Use Case 5: Mixed Permissions#

Scenario: Multiple context paths with different protection levels.

context_paths:
  # Source code - most files writable, some protected
  - path: "/project/src"
    permission: "write"
    protected_paths:
      - "core/constants.py"
      - "version.py"

  # Docs - completely read-only (no protected_paths needed, just use "read")
  - path: "/project/docs"
    permission: "read"

  # Temp folder - fully writable (no protected_paths)
  - path: "/project/temp"
    permission: "write"

How It Works#

Permission Enforcement#

Protected paths are enforced by the PathPermissionManager:

  1. Startup validation: Checks that protected paths exist within their context path

  2. Runtime enforcement: Blocks write/delete operations on protected paths

  3. Clear error messages: Agents receive descriptive errors when blocked

Agent: Edit /project/config.json
Error: Cannot modify /project/config.json - path is protected

Read Operations#

Agents can always read protected files:

Agent: Read config.json        # ✅ Allowed
Agent: Edit config.json         # ❌ Blocked
Agent: Delete config.json       # ❌ Blocked

This allows agents to use protected files as reference material.

Directory Protection#

Protecting a directory protects all contents recursively:

protected_paths:
  - "tests/fixtures/"  # Protects all files inside

✅ Read tests/fixtures/data.json
❌ Write tests/fixtures/data.json
❌ Delete tests/fixtures/
❌ Create tests/fixtures/new_file.txt

Interaction with File Operation Safety#

Protected paths work alongside read-before-delete enforcement:

  1. Protected files: Cannot be deleted even if read first

  2. Non-protected files: Follow standard read-before-delete rules

  3. Agent-created files: Can be deleted (not affected by protection)

Interactive Mode#

In interactive mode, you can add protected paths when prompted:

📂 Context Paths:
   No context paths configured

❓ Add current directory as context path?
   /Users/me/project
   [Y]es (default) / [P]rotected / [N]o / [C]ustom path: P

Enter protected paths (relative to context path), one per line. Empty line to finish:
   → config.json
   → .env
   → tests/fixtures/
   →

✓ Added /Users/me/project (write)
  🔒 config.json
  🔒 .env
  🔒 tests/fixtures/

Advanced Patterns#

Pattern Matching (Future Enhancement)#

Note

Currently, protected paths must be explicit file or directory names. Pattern matching (e.g., *.json) is not yet supported but planned for future releases.

Current workaround - list files explicitly:

protected_paths:
  - "config.json"
  - "secrets.json"
  - "settings.json"

Nested Protection#

You can have multiple levels of protection:

context_paths:
  # Parent directory mostly writable
  - path: "/project"
    permission: "write"
    protected_paths:
      - "src/core/"              # Protect entire core module

  # More specific protection for subdirectory
  - path: "/project/src"
    permission: "write"
    protected_paths:
      - "utils/constants.py"     # Additional specific protection

Troubleshooting#

Protected Path Not Working#

Problem: Agent is modifying a file you marked as protected.

Check:

  1. Verify relative path is correct:

    context_paths:
  - path: "/Users/me/project"
    protected_paths:
      - "config.json"         # ✅ Relative to /Users/me/project
      # NOT: "/Users/me/project/config.json"  # ❌ Would be treated as relative

  2. Check the file exists:

    Protected paths must exist when MassGen starts. Check logs for validation errors.

  3. Verify the context path permission:

    permission: "write"  # Required - protection only applies to writable paths

Path Not Found Error#

Problem: “Protected path ‘file.txt’ not found in context path ‘/project’”

Solution: Ensure the protected path exists before starting MassGen:

# Check if file exists
ls /project/file.txt

# If missing, either:
# 1. Create the file first, or
# 2. Remove it from protected_paths

Agent Still Modifying Files#

Problem: Agent bypasses protection during coordination.

Check:

  1. Ensure you’re using during final presentation: Protection applies to all phases, but ensure agent is using the right context path

  2. Check file is within context path: Protection only works for files within the specified context path

  3. Review logs: Check massgen_debug.log for permission checks

Best Practices#

  1. Be explicit about what to protect: List all critical files rather than assuming default protection

  2. Test first: Run with a test directory to verify protection works as expected

  3. Document in comments: Add comments to your config explaining why files are protected

    protected_paths:
  - "schema.sql"        # Database schema - don't let agents modify structure
  - "LICENSE"           # Legal file - must not change

  4. Use read-only permission when appropriate: If the entire directory should be read-only, use permission: "read" instead of protecting all paths

    # If you want everything read-only:
- path: "/reference_docs"
  permission: "read"     # ← Simpler than listing all files as protected

# If you want selective protection:
- path: "/working_dir"
  permission: "write"
  protected_paths: [...]  # ← Use this for mixed permissions

  5. Combine with planning mode: Use protected paths alongside planning mode for maximum safety

    orchestrator:
  context_paths:
    - path: "/project"
      permission: "write"
      protected_paths: ["config.json"]
  coordination:
    enable_planning_mode: true  # Prevents accidental modifications during coordination

Binary File Protection#

MassGen automatically prevents agents from using text-based read tools on binary files, directing them to use appropriate specialized tools instead.

What’s Protected#

Text-based read tools (read_file, find_and_read_text, grep) are automatically blocked from accessing 40+ binary file types:

Images:

.jpg, .jpeg, .png, .gif, .bmp, .svg, .webp, .tiff

Videos:

.mp4, .avi, .mov, .mkv, .flv, .wmv, .webm, .mpg

Audio:

.mp3, .wav, .ogg, .flac, .aac, .m4a, .wma

Archives:

.zip, .tar, .gz, .7z, .rar

Documents:

.pdf, .docx, .xlsx, .pptx (use understand_file tool)

Executables:

.exe, .bin, .dll, .so, .dylib, .pyc

How It Works#

When an agent attempts to read a binary file with a text tool, they receive a helpful error message:

Cannot read image file 'screenshot.png' with text-based tool 'read_file'.
Please use 'understand_image' tool for image files.

Cannot read video file 'demo.mp4' with text-based tool 'grep'.
Please use 'understand_video' tool for video files.

The error messages automatically suggest the correct tool for each file type:

  • Images → understand_image

  • Videos → understand_video

  • Audio → understand_audio

  • PDF/Office docs → understand_file

  • Archives → Extract first, then read contents

Benefits#

  1. Prevents Confusion: Agents can’t accidentally try to read binary data as text

  2. Better Tool Usage: Guides agents to use appropriate multimodal tools

  3. Clearer Errors: Actionable error messages instead of garbled binary output

  4. No Configuration Needed: Works automatically for all agents

Security Considerations#

Warning

Protected paths are a convenience feature, not a security boundary. They prevent accidental modifications but shouldn’t be relied upon for security-critical files.

For security-sensitive files:

  • Use file system permissions (chmod)

  • Run MassGen with limited user accounts

  • Store sensitive data outside agent-accessible directories

  • Use read-only context paths instead of protected paths

  • Review all agent operations before deploying

Binary file protection is also a convenience feature that guides agents to use correct tools, not a security boundary.

Next Steps#