fix: enforce workspace isolation to prevent agent pollution (#57) (#72)

Problem: After installing Agent Reach, agents may clone repos, create
files, or write output into the workspace directory, gradually polluting
the user's project. Over time this degrades the agent experience.

Fix:
- SKILL.md: add Workspace Rules section — never create files in workspace
- install.md: add Directory Rules table, explicit boundary about workspace
- install.md: all git clone commands now target ~/.agent-reach/tools/
- update.md: add workspace warning
- cli.py: install creates ~/.agent-reach/tools/ directory

All agent-facing docs now enforce: /tmp for temp, ~/.agent-reach/ for
persistent data, workspace stays untouched.

Co-authored-by: Panniantong <panniantong@users.noreply.github.com>

agent_reach/cli.py

@@ -147,6 +147,10 @@ def _cmd_install(args):
     print("👁️  Agent Reach Installer")
     print("=" * 40)
 
+    # Ensure tools directory exists (for upstream tool repos)
+    tools_dir = os.path.expanduser("~/.agent-reach/tools")
+    os.makedirs(tools_dir, exist_ok=True)
+
     if dry_run:
         print("🔍 DRY RUN — showing what would be done (no changes)")
         print()

agent_reach/skill/SKILL.md

@@ -13,7 +13,19 @@ description: >
 
 # Agent Reach
 
-Install and configure upstream tools for 12+ platforms. After setup, call them directly — no wrapper layer.
+Install and configure upstream tools for 13+ platforms. After setup, call them directly — no wrapper layer.
+
+## ⚠️ Workspace Rules
+
+**Never create files, clone repos, or write output in the agent workspace.** Use these directories instead:
+
+| Purpose | Directory |
+|---------|-----------|
+| Temporary output (subtitles, downloads) | `/tmp/` |
+| Upstream tool repos | `~/.agent-reach/tools/` |
+| Config & tokens | `~/.agent-reach/` |
+
+Violating this will pollute the user's workspace and degrade their agent experience over time.
 
 ## Setup
 
@@ -277,7 +289,7 @@ asyncio.run(search())
 
 ```bash
 # Read a WeChat article (returns Markdown with images)
-cd /path/to/wechat-article-for-ai && python3 main.py "https://mp.weixin.qq.com/s/ARTICLE_ID"
+cd ~/.agent-reach/tools/wechat-article-for-ai && python3 main.py "https://mp.weixin.qq.com/s/ARTICLE_ID"
 
 # Run as MCP server (for AI agent integration)
 python3 mcp_server.py

docs/install.md

@@ -30,8 +30,22 @@ When fixing issues, stay within these limits:
 - **DO NOT** modify system files outside `~/.agent-reach/`
 - **DO NOT** install packages not listed in this guide
 - **DO NOT** disable firewalls, security settings, or system protections
+- **DO NOT** clone repos, create files, or run commands inside the agent workspace / working directory
 - If something requires elevated permissions, **tell the user** what's needed and let them decide
 
+### 📁 Directory Rules
+
+All Agent Reach files go in dedicated directories — **never in the agent workspace**:
+
+| Purpose | Directory | Example |
+|---------|-----------|---------|
+| Config & tokens | `~/.agent-reach/` | `~/.agent-reach/config.json` |
+| Upstream tool repos | `~/.agent-reach/tools/` | `~/.agent-reach/tools/douyin-mcp-server/` |
+| Temporary files | `/tmp/` | `/tmp/yt-dlp-output/` |
+| Skills | `~/.openclaw/skills/agent-reach/` | SKILL.md |
+
+**Why?** If you clone repos or create files in the workspace, it pollutes the user's project directory and can break their agent over time. Keep the workspace clean.
+
 ### Step 1: Install
 
 **Default (fully automatic):**
@@ -149,6 +163,7 @@ pip install douyin-mcp-server
 
 # 2. 启动 HTTP 服务（端口 18070）
 # 方式一：用 uv（推荐）
+mkdir -p ~/.agent-reach/tools && cd ~/.agent-reach/tools
 git clone https://github.com/yzfly/douyin-mcp-server.git && cd douyin-mcp-server
 uv sync && uv run python run_http.py
 
@@ -212,6 +227,7 @@ pip install linkedin-scraper-mcp
 > "Boss直聘职位页面可直接读取。完整搜索和打招呼功能需要 mcp-bosszp。"
 
 ```bash
+mkdir -p ~/.agent-reach/tools && cd ~/.agent-reach/tools
 git clone https://github.com/mucsbr/mcp-bosszp.git && cd mcp-bosszp
 pip install -r requirements.txt && playwright install chromium
 ```

docs/update.md

@@ -12,6 +12,10 @@ Copy this to your AI Agent:
 
 ## For AI Agents
 
+### ⚠️ Workspace Rules
+
+**Never create files, clone repos, or run commands in the agent workspace.** Use `/tmp/` for temporary work and `~/.agent-reach/` for persistent data.
+
 ### Goal
 
 Update Agent Reach to the latest version, then verify everything still works.