Bug: Path-sandbox [FILE_OUTSIDE_PROJECT] error when executing skills referencing auxiliary files

[hsm207]

Description

Codebuff officially implements and promotes the use of the skill tool (handleSkill) to execute portably structured SKILL.md workflows. However, the runtime environment strictly blocks standard-compliant skills that attempt to query auxiliary files (such as references, checklists, or rulebooks) packaged within their own directories.

When a skill instructions set directs the agent to read a file located in ~/.agents/skills/<skill-name>/references/..., the SDK's sandbox check fails with a [FILE_OUTSIDE_PROJECT] status code.

Standard Alignment

According to the official Agent Skills open standard (agentskills.io):

• A skill package structure officially includes optional references/ and assets/ directories:

  my-skill/
  ├── SKILL.md       # Required: metadata + instructions
  ├── scripts/       # Optional: executable code
  ├── references/    # Optional: documentation
  └── assets/        # Optional: templates, resources
  

• The standard execution specification mandates:

  "3. Execution: The agent follows the instructions, optionally executing bundled code or loading referenced files as needed."

Reproduction / Verification

The sandbox boundary is hardcoded and officially verified to block all out-of-bounds relative reads in the SDK's own test suite inside sdk/src/__tests__/read-files.test.ts:

• should return OUTSIDE_PROJECT for absolute paths outside project
• should return OUTSIDE_PROJECT for relative paths that escape project

Because any globally stored skill resides in ~/.agents/skills/ (outside the active project workspace root), any call to read references via read_files triggers these test-enforced path rejections.

Root Cause Analysis

1. Strict Path Resolution: In sdk/src/tools/path-utils.ts, the resolveFilePathWithinProject method only verifies paths relative to a single static projectRoot (cwd). If a path starts with .., it fails escapesProject() and is immediately discarded as out-of-bounds.
2. No Whitelisting: The SDK's file validation and context structures have no mechanism to dynamically whitelist directories outside the primary active project root.

Suggested Fix

We can resolve this by introducing a session-scoped whitelisting array allowedSkillDirs in ProjectFileContext:

1. Whitelist on Activation: When handleSkill loads a skill from disk, dynamically register its directory in fileContext.allowedSkillDirs.
2. Sandbox Exemption: Modify resolveFilePathWithinProject to permit path resolution if a requested file is a subdirectory of any folder registered in allowedSkillDirs.
3. Bypass Gitignore: In getFiles (sdk/src/tools/read-files.ts), skip project gitignore checks for whitelisted paths starting with ...

---

I am happy to take on this issue and submit a PR once we agree on the proposed approach!