Skip to content

Add additional working directories to Agent sessions #682

Description

@taras

Story

As an executable-document author, I want an Agent session to work in specified
directories beyond its primary working directory, so one session can work
across related projects without gaining access to unrelated files.

Example outcome

A session starts in /work/product and also receives access to
/work/shared-docs and /work/design-system.

  • /work/product remains the session's primary working directory.
  • The Agent can use only the additional directories the document requested and
    the host authorized.
  • Specifying a directory requests access; it does not grant access by itself.
  • A provider that cannot enforce the exact directory access must refuse before
    starting Agent work. Here, a provider is the adapter that launches or connects
    to the coding Agent.

The public Markdown spelling for requesting these directories remains an
architecture decision. This issue must settle that spelling before
implementation begins.

Current gap

XMD's session-launch request and durable resume record already contain an
ordered additionalDirectories field, but every session records an empty list.
There is no Markdown component for adding a directory, and no provider maps an
additional directory into an Agent session.

#517 delivered prepared native session launch and intentionally left this
capability for a separate story.

Decisions required

Before implementation, settle:

  • how an author specifies an additional directory and where that declaration may
    appear;
  • how relative paths resolve;
  • whether access can be read-only or read-write, and whether an omitted mode has
    a default;
  • how ordering, duplicates, overlapping directories, and conflicting modes
    behave;
  • how the trusted host confirms that every directory is within the filesystem
    access it may grant;
  • how the directory set becomes part of session identity, preventing reuse of a
    session created with different access;
  • what XMD retains so an interrupted session can resume with the same directory
    contract without exposing unauthorized host paths;
  • how each provider reports and enforces the access modes it supports; and
  • which ordinary runs and session-launch profiles may offer the capability.

Workflow Agents continue to receive repository observations through
XMD-mediated operations. This issue does not give them direct access to the
retained workflow Workspace.

Acceptance

  • One Agent session receives its primary working directory and two additional
    directories the host authorized, in stable order.
  • Adding directories does not change the primary working directory or insert
    file contents into the Agent's instructions.
  • Empty, escaping, conflicting, and unauthorized paths refuse before provider
    work begins.
  • Duplicate and overlapping paths follow one documented rule.
  • A requested access mode is enforced exactly or refused as unsupported.
  • A session created with one directory set cannot be silently reused with
    another.
  • Resuming an incomplete session requires both the retained directory contract
    and current host authorization. Replaying completed work starts no provider.
  • Success, failure, and cancellation leave no temporary access or provider
    ownership behind.
  • Deterministic tests cover resolution, ordering, conflicts, authorization,
    provider support, session reuse, resumption, and cleanup.
  • A provider advertises additional-directory support only after an opt-in
    integration test proves its mapping.

Out of scope

  • Automatically discovering or injecting nested AGENTS.md files.
  • Giving workflow Agents direct access to retained Workspace materialization.
  • Claiming filesystem containment for arbitrary JavaScript, subprocesses, or
    providers that cannot enforce it.
  • Delivering the broader least-authority Quest in Quest: Enforce least authority across xmd workflows #536.

Related work

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or requestsecuritySecurity hardening

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions