docs(claude.md): document action sandbox vs internal workspace split

[CodeGhost21]

Summary

• Documents the action_dir vs workspace_dir split shipped in feat(security): separate agent action sandbox from internal workspace state #3074 — previously only discoverable by reading SecurityPolicy source.
• Names the OPENHUMAN_ACTION_DIR env override, the default fallback chain (default_action_dir → default_projects_dir), and the precedence rule.
• Points contributors at the source of truth for the internal-state denylist: WORKSPACE_INTERNAL_DIRS / WORKSPACE_INTERNAL_FILES at src/openhuman/security/policy.rs:173-202, surfaced via is_workspace_internal_path at policy.rs:1097.

Problem

PR #3074 introduced Config.action_dir, the internal-state denylist, and the rule that acting tools (shell, node_exec, npm_exec, file_write, edit_file, apply_patch, git_operations) default their CWD to action_dir rather than workspace_dir. None of this was written down — grep action_dir CLAUDE.md was empty.

Concrete effect: a new contributor reading CLAUDE.md saw the existing "Agent access mode" paragraph describing workspace_only / trusted_roots / default_projects_dir and reasonably concluded that Config.workspace_dir is still where the agent operates. That's wrong post-#3074, and audit follow-up #3239 flagged it as a doc gap against issue #3051 criterion 4 ("Projects alignment is documented").

Solution

Adds a new "Action sandbox vs internal workspace" paragraph under ## Configuration, directly after the existing "Agent access mode" paragraph. The new paragraph:

• Names both action_dir and workspace_dir as distinct Config fields with the file pointer (src/openhuman/config/schema/types.rs).
• States the routing rule plainly: acting tools resolve to action_dir, not workspace_dir.
• Lists every internal subtree and secret file by name (16 dirs + 7 files), matching the source-of-truth constants.
• Points at is_workspace_internal_path (policy.rs:1097) and the underlying constants (policy.rs:173-202) as the canonical denylist.
• Clarifies the env override precedence: setting OPENHUMAN_ACTION_DIR does not weaken the internal denylist; workspace_dir is always blocked even if action_dir happens to overlap.
• Notes the maintenance contract: adding a new internal-state subdir requires extending WORKSPACE_INTERNAL_DIRS in the same change.

Surgical 7-line addition; no other content edited. Verified prettier on the new content (the pre-existing CLAUDE.md has unrelated prettier drift in table column alignment and blank-line-before-list rules; not in scope here).

Submission Checklist

If a section does not apply to this change, mark the item as N/A with a one-line reason. Do not delete items.

• Tests added or updated — N/A: docs-only change to CLAUDE.md, no executable behavior.
• Diff coverage ≥ 80% — N/A: docs-only change, no source lines touched.
• Coverage matrix updated — N/A: no feature rows added, removed, or renamed.
• All affected feature IDs from the matrix are listed — N/A: no feature behavior changed.
• No new external network dependencies introduced.
• Manual smoke checklist updated if this touches release-cut surfaces — N/A: docs-only, no smoke surface touched.
• Linked issue closed via Closes #NNN in the ## Related section.

Impact

• Runtime/platform impact: none — CLAUDE.md is contributor documentation only, not bundled or loaded at runtime.
• Performance/security/migration/compatibility: none.

Related

• Closes: Document action sandbox vs internal-workspace split in CLAUDE.md #3239
• Parent issue (audit punch list): Dedicated jailed actions directory separate from internal workspace #3051
• Implementing PR that shipped the code being documented: feat(security): separate agent action sandbox from internal workspace state #3074
• Sibling follow-ups from the same audit: Wire cwd_jail into shell, node_exec, and npm_exec tools #3235 (cwd_jail wiring), Update coding-agent prompts to reference action sandbox instead of "the workspace" #3236 (agent prompts), AgentAccessPanel should display live action_dir and workspace_dir via RPC #3237 (live paths in AgentAccessPanel), Add pwd-asserts-action_dir test for shell-family tools (unit + JSON-RPC E2E) #3238 (pwd tests), Make action_dir editable in Settings UI (currently env/TOML only) #3240 (Settings UI editor).

---

AI Authored PR Metadata (required for Codex/Linear PRs)

Keep this section for AI-authored PRs. For human-only PRs, mark each field N/A.

Linear Issue

• Key: N/A — work is tracked in GitHub issue Document action sandbox vs internal-workspace split in CLAUDE.md #3239, not Linear.
• URL: N/A

Commit & Branch

• Branch: followup/3239-document-action-sandbox (on fork CodeGhost21/openhuman)
• Commit SHA: c855cbffd3d2783501dde2a799223d7fdd437d89

Validation Run

• pnpm --filter openhuman-app format:check — N/A: pre-existing CLAUDE.md prettier drift unrelated to this change; new content is prettier-clean in isolation.
• pnpm typecheck — N/A: docs-only.
• Focused tests: N/A — docs-only.
• Rust fmt/check (if changed): N/A — no Rust touched.
• Tauri fmt/check (if changed): N/A — no Tauri touched.

Validation Blocked

• command: N/A
• error: N/A
• impact: N/A

Behavior Changes

• Intended behavior change: none — documentation only.
• User-visible effect: contributors reading CLAUDE.md discover the action sandbox / internal workspace split without grepping the policy source.

Parity Contract

• Legacy behavior preserved: yes — no code changed.
• Guard/fallback/dispatch parity checks: N/A.

Duplicate / Superseded PR Handling

• Duplicate PR(s): none.
• Canonical PR: this one.
• Resolution: N/A.

Summary by CodeRabbit

• Documentation
  • Updated documentation clarifying the filesystem sandbox architecture, including distinctions between agent-accessible and internal system directories and how security restrictions are enforced.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: bc3b17f4-1df4-4b11-be81-3d8d263e7556

📥 Commits

Reviewing files that changed from the base of the PR and between 8476248 and c855cbf.

📒 Files selected for processing (1)

• CLAUDE.md

---

📝 Walkthrough

Walkthrough

This PR adds a documentation subsection to CLAUDE.md that clarifies the distinction between action_dir (the agent's read/write root used by acting tools) and workspace_dir (internal product state that acting tools cannot access). It explains the fail-closed denylist enforcement mechanism and canonicalization requirements to prevent symlink escape.

Changes

Action Sandbox and Internal Workspace Documentation

Layer / File(s)

Summary

Action sandbox and internal workspace documentation CLAUDE.md

Documents that Config.action_dir is the agent's read/write root and default base for acting tools (shell, node, npm, file operations, git, codegraph), while workspace_dir is reserved for internal product state. Explains the fail-closed denylist enforcement (independent of access tier, applied after canonicalization), the need to extend denylist constants for new internal subdirectories, and that relocating OPENHUMAN_ACTION_DIR does not weaken the internal block.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

Possibly related issues

• #3236: This change directly addresses the gap identified regarding documentation of action_dir vs workspace_dir and denylist enforcement, supporting agent prompts that reference the correct sandbox boundaries.

Suggested reviewers

• graycyrus

Poem

🐰 A sandbox split, now crystal clear—
action_dir the stage, workspace_dir held dear,
Denylists guard the inner shrine,
With canonicalization's trusty line!
Documentation shines, no escapes to fear. ✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: documenting the action sandbox vs internal workspace split in CLAUDE.md.
Linked Issues check	✅ Passed	The PR successfully addresses all acceptance criteria from issue #3239: documents action_dir, workspace_dir, OPENHUMAN_ACTION_DIR override, tool routing rule, internal denylist, default-vs-override relationship, and calls out docs-only status.
Out of Scope Changes check	✅ Passed	The PR contains only a documentation-only change to CLAUDE.md adding 7 lines that are directly scoped to document the action sandbox vs internal workspace split as specified in issue #3239.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}