Workspace Isolation

​

What’s in the Box

• Hooks manifest (hooks/hooks.json) - Two PreToolUse hooks (one for terminal, one for file_editor) whose validation logic is inlined as POSIX-sh commands
• Reference scripts (hooks/scripts/*.sh) - The same logic as standalone files, kept for readability/diffing (see the note under Hook Scripts on why the manifest inlines them rather than referencing these files)
• Skill (skills/sandbox-enforcer/SKILL.md) - Documentation about isolation rules
• Plugin manifest (.claude-plugin/plugin.json) - Standard Claude Code plugin format

​

The Problem This Solves

~/my-projects/
├── web-app/      ← Conversation 1: "Refactor the auth module"
├── api-server/   ← Conversation 2: "Add rate limiting"
└── cli-tool/     ← Conversation 3: "Fix the parser bug"

• Agent 1 might accidentally cd ../api-server and modify the wrong project
• Agent 2 could rm -rf ../web-app/node_modules while cleaning up
• Agent 3 might write test output to /tmp that conflicts with other agents

• Each agent stays in its assigned directory
• Attempts to navigate or write outside are blocked with helpful messages
• Agents can still READ external files (with # read-only escape hatch)

​

How It Works

​

Protected Operations

​

Terminal Commands

• Navigation: cd, pushd, popd to external directories
• Write operations: rm, mv, cp, chmod, mkdir, touch, dd, ln, etc.
• Output redirection: >, >> to external paths

​

File Editor Operations

• Write commands: create, str_replace, insert, undo_edit to external paths
• Read commands: view is always allowed (can read anywhere)

​

Run It

• Local Development Setup
• Via API
• Via Badge

1. Create multiple project directories:

mkdir -p ~/my-projects/{project-a,project-b,project-c}

2. Load the plugin in each conversation with different workspace dirs:

# Conversation 1 - workspace: ~/my-projects/project-a
cd ~/my-projects/project-a
# Load plugin with load-plugin example

# Conversation 2 - workspace: ~/my-projects/project-b
cd ~/my-projects/project-b
# Load plugin with load-plugin example

3. Try cross-contamination (it will be blocked):

# In Conversation 1
cd ../project-b  # BLOCKED
cp file.txt ../project-b/  # BLOCKED

cd ../load-plugin

# This will be blocked (cd outside workspace)
python load_plugin.py \
  --repo-path workspace-isolation/sandbox-enforcer \
  --message "Navigate to /tmp and list files there"

# This will be allowed (within workspace)
python load_plugin.py \
  --repo-path workspace-isolation/sandbox-enforcer \
  --message "List all files in the current directory"

​

The # read-only Escape Hatch

# ✓ Allowed - read-only access to system file
cat /etc/os-release  # read-only

# ✓ Allowed - check system information
uname -a  # read-only

# ✗ Still blocked - write operation
echo "data" > /tmp/output.txt  # read-only  (doesn't help with writes)

​

Hook Scripts

​

1. Terminal Validation (validate_terminal.sh)

• Navigation commands (cd, pushd, popd) trying to leave workspace
• Write commands (rm, mv, cp, chmod, mkdir, etc.) targeting external paths
• Output redirects (>, >>) to external files

#!/bin/bash
input=$(cat)
workspace="${OPENHANDS_PROJECT_DIR:-$PWD}"

# Check for navigation outside workspace
if [[ command is cd/pushd/popd to external path ]]; then
    echo '{"decision": "deny", "reason": "Cannot navigate outside workspace..."}'
    exit 2
fi

# Check for write operations outside workspace
# ...

​

2. File Editor Validation (validate_file_editor.sh)

• Always allows view (read-only)
• Blocks create, str_replace, insert, undo_edit to external paths

#!/bin/bash
input=$(cat)
workspace="${OPENHANDS_PROJECT_DIR:-$PWD}"

# Always allow view
if [[ command == "view" ]]; then
    exit 0
fi

# Block writes outside workspace
# ...

​

Workspace Detection

1. OPENHANDS_PROJECT_DIR - Set by OpenHands Cloud/Enterprise
2. PWD - Current working directory (fallback)

​

Plugin Structure

sandbox-enforcer/
├── .claude-plugin/
│   └── plugin.json              # Plugin metadata
├── hooks/
│   ├── hooks.json               # Hook config (validators inlined as POSIX-sh commands)
│   └── scripts/
│       ├── validate_terminal.sh     # Reference copy of the terminal validator
│       └── validate_file_editor.sh  # Reference copy of the file_editor validator
└── skills/
    └── sandbox-enforcer/
        └── SKILL.md             # Documentation (auto-loaded)

​

Comparison with Other Examples

​

When to Use This

• Running multiple parallel conversations on one machine
• Each conversation works on a different project/directory
• You need to prevent cross-contamination between workspaces
• Building multi-tenant local development environments
• Teaching/educational scenarios with multiple students

• Using cloud ephemeral workspaces (already isolated by containers)
• Running only one conversation at a time
• The agent needs to work across multiple project directories intentionally

​

Real-World Example: LXA

lxa schedule --all  # Process all jobs in parallel, each in its own workspace
├── Job 1: /data/job-1234/  (isolated)
├── Job 2: /data/job-5678/  (isolated)
└── Job 3: /data/job-9012/  (isolated)

​

Limitations

1. No full shell parsing - Complex quoting might bypass detection
2. No path canonicalization - Doesn’t resolve symlinks or . / .. fully
3. Simplified command extraction - May not catch all edge cases
4. Fails open - If hook can’t parse input, it allows the operation (for safety)

• Full path resolution with pathlib
• Symlink following
• Complex shell command parsing with shlex
• Proper handling of shell metacharacters and quoting

​

Extending the Example

# Add more blocked write commands, e.g. npm and pip:
if printf '%s' "$cmd_name" | grep -qE "^(rm|rmdir|mv|cp|chmod|chown|mkdir|touch|dd|ln|npm|pip)$"; then
    # ...
fi

​

Contributing

​

Related