Introduction

When developing Agents using DeepSeek Harness (DSH), an Agent typically has full access to the entire workspace by default. This full visibility can lead to permission overreach, accidental operations, or exposure of sensitive directories. dsh-session-scope is intended to address this issue by providing an independent session-level workspace visibility layer.

The plugin’s core design principle is: Permissions != Scope. Permissions determine what an Agent can do to files (read-only, write, or full access), while scope determines which directories an Agent can see. It allows exposing only selected directories to the Agent while keeping the session’s original workspace unchanged.

Plugin Positioning

  • Name: dsh-session-scope
  • Maintainer: xarleyn
  • Category: admin-security
  • Core Value: Provides three session scope states—full, focused, and isolated—and limits an Agent’s visibility and operational scope through code-level filesystem projection and Linux process isolation mechanisms.

Core Features

  • Separation of Permissions and Scope: Manages permissions (read-only, workspace-write, danger-full-access) and scopes (full, focused, isolated) independently.
  • Session-Level Projection: Uses the session-scope projection to filter directory listings and search roots, hiding unselected files.
  • Linux Process Isolation: On the Linux backend, the isolated state uses bubblewrap configuration files to strongly isolate the creation of bash and PTY, restricting child process behavior.
  • Command Support: Provides the /scope command for dynamically switching scope states.

Installation and Configuration

The repository has been archived and set to read-only. New development and releases have been migrated to the xarleyn/dsh-plugins monorepo, with the published package name @yadsh/dsh-session-scope.

The old installation command is still available, but it is recommended to use the new package name:

npm install dsh-session-scope

or

npm install @yadsh/dsh-session-scope

Prerequisites: Node.js 20 or higher.

Typical Usage

After installing the plugin, DSH loads cordis.patch.yml and exposes services. Set the current session state using the /scope command:

  1. Set Full Access:
    /scope full
  1. Set Focused Scope:
    /scope focused
  1. Set Isolated Scope:
    /scope isolated

At the same time, session permissions can be set. For example, set the permission to read-only:

# Set permission to read-only

Use Cases and Limitations

  • Use Cases: Scenarios requiring fine-grained control over Agent working directories, preventing Agents from accessing sensitive configuration files, or running Agents in multi-tenant or sandbox environments.
  • Linux Dependency: The isolated state depends on the Linux backend and requires enabling the bubblewrap configuration file. On macOS or Windows backends, isolated is not available.
  • Process Limitations: focused mode only restricts DSH’s file service and does not restrict arbitrary Shell processes. Only isolated mode can restrict bash and PTY processes on Linux.
  • Combination Limitations: The isolated state currently cannot be combined with the danger-full-access permission; otherwise, it fails closed.
  • License: The upstream directory selector portion is licensed under the MIT License.

Summary

dsh-session-scope provides DSH with basic security isolation capabilities. With the /scope command and permission controls, developers can build safer Agent workflows. The project has currently been migrated to the xarleyn/dsh-plugins repository.