Workspace Trust & Context Switching

Workspace trust

WorkspaceTrustManager tracks which local directories the user has explicitly trusted. The trust list is persisted at ~/.umbra/trusted-paths.json.

Why it exists: fs.cd changes the agent’s working directory — and therefore the scope of every subsequent tool call. Switching into an untrusted directory without acknowledgement could silently expand the attack surface of a running agent. The trust gate ensures the user always sees and approves the target path before the agent can act inside it.

Evaluation: when the agent calls fs.cd, the permission system checks whether the resolved target path falls under a trusted ancestor:

trusted: /home/user/projects
  → /home/user/projects/myapp      ✓  (prefix match)
  → /home/user/projects/myapp/src  ✓  (deeper child)
  → /home/user/other               ✗  → interactive prompt

The check is case-insensitive and uses path.normalize to handle different path separators.

User response options at the interactive prompt:

• y — allow this switch once
• n — deny
• a (always) — trust the path permanently, add to trusted-paths.json

Trust entries survive daemon restarts. Removing trust requires editing ~/.umbra/trusted-paths.json directly.

Context switching (fs.cd)

When the agent switches context via fs.cd:

1. The agent’s cwd for all subsequent tool calls updates to the new path
2. The project path changes — the next turn will load a different repo map, different instruction files (UMBRA.md/AGENTS.md/etc.), and different permission rules (umbra.permissions.json)
3. Conversation history and memory from the old context persist in the session

This makes fs.cd a first-class navigation primitive: the agent can move between sub-projects within a monorepo without starting a new thread, while the user retains visibility and control over every directory switch.

Bootstrap context

On each run, gatherBootstrapContext() injects a lightweight system context block into the system prompt:

# Platform Bootstrap Context
- OS: linux 6.1.0
- Shell: /bin/bash
- Node: v22.11.0
- Project: /home/user/myapp
- Git: yes
- Package Manager: pnpm

The OS username is intentionally omitted — it is the machine account name, not the user’s real name, and using it would produce awkward “Hello, DESKTOP-XYZ7K!” greetings. The project path, git presence, and package manager are the operationally relevant facts.