totopo 2.0.0 → 2.1.0-rc-2

package/README.md

@@ -25,7 +25,7 @@ totopo organises work around **projects** — any local directory you register w
 - **Runtime Mode** — adjust runtime mode and installed tools
 - **Rebuild container** — rebuild the docker image (upon changing runtime mode)
 
-All config lives in `~/.totopo/` — nothing is written to your project by default.
+All config lives in `~/.totopo/` — nothing is written to your project directory.
 
 ### Concurrent Sessions
 totopo uses one Docker container per project, not one per session. You can open as many terminal sessions as you need — they all connect to the same container, keeping resource usage bounded and reconnections fast.
@@ -53,11 +53,11 @@ npx totopo
 ## Core features at a glance
 
 - **Docker isolation** — AI agents run in a container with strict filesystem and privilege boundaries
-- **Agents can't reach remote** — push, pull, fetch, and clone are blocked inside the container, preventing agents from accidentally affecting your remote repositories
-- **AI CLIs with persistent sessions** — OpenCode, Claude Code, and Codex are pre-installed, with conversation history that survives restarts and rebuilds
-- **Host-mirror or full runtime** — either match the container environment to your host, or use a standard dev container with the latest stable tools
-- **Agents are scope-aware** — agents are informed of the mounted files and constraints at session start, so they can factor that into how they work
-- **Scoped access** — expose only the files and directories the agent needs
+- **No remote git access** — push, pull, fetch, and clone are blocked inside the container, so agents can't accidentally affect your remote repositories
+- **Scoped access** — expose only the files and directories the agent needs; agents are informed of their scope and constraints at session start
+- **AI CLIs included** — OpenCode, Claude Code, and Codex are pre-installed and ready to use
+- **Persistent agent memory** — conversation history and session data survive container restarts and rebuilds; if your project has its own `.claude/`, `.codex/`, or `.opencode/` directories, they pass through into the container — otherwise they are stored in `~/.totopo/`
+- **Host-mirror or standard runtime** — match the container environment to your host, or use a general-purpose dev container with the latest stable tools
 
 ## Features in Detail
 
@@ -99,7 +99,7 @@ Scoped sessions are well-suited for focused tasks where you want to give the age
 <!-- Example showcasing agent awareness of selective scope limitations:-->
 <!-- ![Scoped access](.github/assets/demo-scoped.gif) -->
 
-### AI CLIs with persistent sessions
+### AI CLIs included
 
 The container comes with the major AI coding CLIs ready to use out of the box:
 
@@ -109,20 +109,24 @@ claude      # Claude Code (Anthropic)
 codex       # Codex (OpenAI)
 ```
 
-Agent session data is isolated per project, so agents do not bleed context between projects. To clear memory, run `npx totopo` and navigate to `Manage totopo > Clear agent memory` and select a project. This stops the container if running and removes the agents directory.
+### Persistent agent memory
+
+Agent session data is isolated per project and persists across container restarts and rebuilds. If your project has its own `.claude/`, `.codex/`, or `.opencode/` directories, they pass through into the container so the AI CLI can read your project-level config. If they don't exist, totopo redirects writes to `~/.totopo/` so nothing is created in your project directory.
+
+To clear memory, run `npx totopo` and navigate to `Manage totopo > Clear agent memory` and select a project. This stops the container if running and removes the agents directory.
 
 ### Dev container runtime
 
 Choose between two modes:
 
 - **Host-mirror** — the container runtime matches your host Node.js version and selected tools, keeping the environment consistent with your local setup.
-- **Full** — a full dev container with the latest stable versions of all tools. Good default if you do not need version parity with your host.
+- **Standard** — a general-purpose dev container with the latest stable versions of all tools. Good default if you do not need version parity with your host.
 
 Either way, basic dev tools and all three AI CLIs are always included.
 
 ## What gets installed
 
-All totopo config lives in `~/.totopo/` on your machine — nothing is written to your project directory unless you opt in.
+All totopo config lives in `~/.totopo/` on your machine — nothing is written to your project directory.
 
 ```text
 ~/.totopo/
@@ -136,7 +140,9 @@ All totopo config lives in `~/.totopo/` on your machine — nothing is written t
         └── agents/             # agent session data — created on first session start
             ├── claude/         # mounted as ~/.claude/
             ├── opencode/       # mounted as ~/.config/opencode/ + ~/.local/share/opencode/
-            └── codex/          # mounted as ~/.codex/
+            ├── codex/          # mounted as ~/.codex/
+            └── workspace/      # shadow mounts — used when the project doesn't have
+                                # its own .claude/, .codex/, or .opencode/ dirs
 ```
 
 Agent session history and conversation data are persisted in the `agents/` directory across container rebuilds and restarts.

package/bin/totopo.js

@@ -148,7 +148,7 @@ while (showMenu) {
             showMenu = true;
             break;
         case "manage-totopo": {
-            const result = await advanced(packageDir);
+            const result = await advanced(packageDir, project.id);
             if (result === "back") showMenu = true;
             break;
         }

package/dist/commands/advanced.js

@@ -152,6 +152,51 @@ async function resetApiKeys(packageDir) {
     cpSync(join(packageDir, "templates", "env"), globalEnvPath);
     log.success(`API keys reset. Edit ${globalEnvPath} to add your keys.`);
 }
+// --- Uninstall projects (multi-select, remove container + image + project dir) -----------------------------------------------------------
+async function uninstallProjects(currentProjectId) {
+    const projects = listProjects();
+    if (projects.length === 0) {
+        log.info("No registered projects.");
+        return;
+    }
+    // Show current project first if known
+    const sorted = currentProjectId
+        ? [...projects].sort((a, b) => (a.id === currentProjectId ? -1 : b.id === currentProjectId ? 1 : 0))
+        : projects;
+    const selected = await multiselect({
+        message: "Select projects to uninstall:",
+        options: sorted.map((p) => ({
+            value: p.id,
+            label: p.meta.displayName,
+            hint: p.meta.projectRoot + (p.id === currentProjectId ? " (current)" : ""),
+        })),
+        required: false,
+    });
+    if (isCancel(selected)) {
+        cancel();
+        return;
+    }
+    for (const id of selected) {
+        const p = projects.find((x) => x.id === id);
+        if (!p)
+            continue;
+        // Stop and remove container if it exists (running or exited)
+        const psResult = spawnSync("docker", ["ps", "-a", "--filter", `name=${p.meta.containerName}`, "--format", "{{.Names}}"], {
+            encoding: "utf8",
+        });
+        const containers = (psResult.stdout ?? "").trim().split("\n").filter(Boolean);
+        for (const c of containers) {
+            log.step(`Stopping and removing container ${c}...`);
+            stopAndRemoveContainer(c);
+        }
+        // Remove Docker image if it exists (image name = container name)
+        log.step(`Removing image ${p.meta.containerName}...`);
+        spawnSync("docker", ["rmi", p.meta.containerName], { stdio: "inherit" });
+        // Delete project directory
+        rmSync(p.projectDir, { recursive: true, force: true });
+        log.success(`Uninstalled project ${p.meta.displayName}.`);
+    }
+}
 // --- Uninstall totopo (global - wipes ~/.totopo/ and all containers/images) --------------------------------------------------------------
 async function uninstallTotopo() {
     const confirmed = await text({
@@ -189,7 +234,7 @@ async function uninstallTotopo() {
     outro("totopo uninstalled. Re-run npx totopo to set up again.");
 }
 // --- Manage totopo menu ------------------------------------------------------------------------------------------------------------------
-export async function run(packageDir) {
+export async function run(packageDir, currentProjectId) {
     while (true) {
         const action = await select({
             message: "Manage totopo:",
@@ -199,6 +244,7 @@ export async function run(packageDir) {
                 { value: "remove-images", label: "Remove images", hint: "pick images to remove" },
                 { value: "reset-keys", label: "Reset API keys", hint: "overwrites ~/.totopo/.env" },
                 { value: "doctor", label: "Doctor", hint: "check Docker health" },
+                { value: "uninstall-project", label: "Uninstall project", hint: "pick projects to remove" },
                 { value: "uninstall", label: "Uninstall totopo", hint: "wipe ~/.totopo/ and all containers/images" },
                 { value: "back", label: "← Back" },
             ],
@@ -219,6 +265,9 @@ export async function run(packageDir) {
             case "reset-keys":
                 await resetApiKeys(packageDir);
                 break;
+            case "uninstall-project":
+                await uninstallProjects(currentProjectId);
+                break;
             case "doctor":
                 await runDoctor(null, true);
                 await sleep(500);

package/dist/commands/dev.js

@@ -5,8 +5,9 @@
 import { spawnSync } from "node:child_process";
 import { existsSync, mkdirSync, readdirSync, statSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
-import { dirname, join, relative } from "node:path";
+import { join, relative } from "node:path";
 import { cancel, confirm, groupMultiselect, isCancel, log, multiselect, note, outro, path, select } from "@clack/prompts";
+import { buildAgentContextDocs, buildAgentMountArgs, injectAgentContext, resolveShadowedDirs, } from "../lib/agent-context.js";
 // The project config dir is always mounted here inside the container (read-only)
 const TOTOPO_CONTAINER_PATH = "/home/devuser/.totopo";
 // --- Prompt: scope selection -------------------------------------------------------------------------------------------------------------
@@ -212,25 +213,11 @@ async function promptSelectivePaths(cwd) {
     }
     return result;
 }
-// --- Build agent mount args --------------------------------------------------------------------------------------------------------------
-// Creates agents/ subdirectories in the project dir on the host (lazily) and
-// returns volume mount args for all supported agent tools.
-function buildAgentMountArgs(projectDir) {
-    const agentsDir = join(projectDir, "agents");
-    const mounts = [
-        { host: join(agentsDir, "claude"), container: "/home/devuser/.claude" },
-        { host: join(agentsDir, "opencode", "config"), container: "/home/devuser/.config/opencode" },
-        { host: join(agentsDir, "opencode", "data"), container: "/home/devuser/.local/share/opencode" },
-        { host: join(agentsDir, "codex"), container: "/home/devuser/.codex" },
-    ];
-    for (const { host } of mounts)
-        mkdirSync(host, { recursive: true });
-    return mounts.flatMap(({ host, container }) => ["-v", `${host}:${container}`]);
-}
 // --- Build mount args --------------------------------------------------------------------------------------------------------------------
 // Project config dir is always explicitly mounted - it's never inside the workspace.
 function buildMountArgs(scope, workspaceDir, projectDir, cwd) {
-    const agentMounts = buildAgentMountArgs(projectDir);
+    const hostWorkspaceDir = scope.mode === "repo" ? workspaceDir : cwd;
+    const agentMounts = buildAgentMountArgs(projectDir, hostWorkspaceDir);
     const configMount = ["-v", `${projectDir}:${TOTOPO_CONTAINER_PATH}:ro`];
     if (scope.mode === "repo") {
         return ["-v", `${workspaceDir}:/workspace`, ...configMount, ...agentMounts];
@@ -310,97 +297,24 @@ function scopesMatch(selected, existing, workspaceDir) {
     }
     return true;
 }
-// Assembles the agent context markdown injected into each supported agent's config dir at session start
-function buildAgentContextDocs(scope) {
-    // -- Scope section --------------------------------------------------------------------------------------------------------------------
-    let scopeSection;
-    if (scope.mode === "repo") {
-        scopeSection = `## Workspace scope: repo
-
-You have access to the full repository at \`/workspace\`. Some operations (git push, system-level changes) require running on the host.`;
-    }
-    else if (scope.mode === "cwd") {
-        scopeSection = `## Workspace scope: cwd
-
-Workspace is scoped to one directory (\`${scope.hostCwd}\`). Files outside it are not visible to you. Commands that depend on absent files will fail.`;
-    }
-    else {
-        const pathList = scope.selectedPaths.map((p) => `- \`/workspace/${p}\``).join("\n");
-        scopeSection = `## Workspace scope: selective
-
-Workspace is selectively scoped. Only the following paths are mounted:\n\n${pathList}`;
-    }
-    // -- Git section ----------------------------------------------------------------------------------------------------------------------
-    let gitSection;
-    if (scope.mode === "repo") {
-        gitSection = `## Git availability
-
-Git is fully available for local operations (commit, branch, log, diff, status, etc.).
-
-Remote access (push, pull, fetch, clone) is **blocked at the system level** by design — \`protocol.allow = never\` is enforced in \`/etc/gitconfig\` and cannot be overridden without root. This is a deliberate security boundary: the container has no access to remote repositories. Ask the user to run any remote git operations from the host.`;
-    }
-    else {
-        gitSection = `## Git availability
-
-Git local operations are **not available** in this scope — \`.git\` is not mounted. This is intentional: mounting \`.git\` would expose the full commit history of all repository files, including those outside your current mount, defeating the security boundary of scoped access.
-
-Remote access is also **blocked container-wide** by design (\`protocol.allow = never\` in \`/etc/gitconfig\`).
-
-If git operations are needed, ask the user to run them on the host.`;
-    }
-    // -- Selective-only warning -----------------------------------------------------------------------------------------------------------
-    const selectiveWarning = scope.mode === "selective"
-        ? `\n\n## Selective scope: file creation warning
-
-Any file you create **outside your mounted paths** (e.g. at \`/\`, \`/tmp\`, or any path not listed above) will **not be visible on the host** and will be lost when the container is rebuilt.
-
-If the user asks you to create or modify a file at such a location:
-1. Notify the user that the path is outside your mounted workspace.
-2. Explain that files created there will not sync to the host.
-3. Suggest the user run the command on the host instead, or confirm they want the file only inside the container (understanding it will be lost on rebuild).`
-        : "";
-    // -- Responsibilities section ---------------------------------------------------------------------------------------------------------
-    const responsibilitiesSection = `## Your responsibilities at session start
-
-At the start of every session:
-- Briefly surface your current workspace scope and its limitations to the user.
-- Tell the user what you cannot access in this session (files, git, remotes).`;
-    // -- Assemble per-tool - only the self-referencing path differs -----------------------------------------------------------------------
-    function build(toolPath) {
-        const constraintsSection = `## Constraints
-
-- Files outside mounted paths cannot be read, written, or executed.
-- If a command fails because of missing files, tell the user: "I have limited workspace scope — please run \`<command>\` on the host."
-- \`~/.totopo/\` is read-only inside the container.
-- This file (\`${toolPath}\`) is managed by totopo and overwritten on every session start. Do not edit it.`;
-        return ([
-            "# totopo Workspace Context\n\nYou are running inside a totopo dev container.\n",
-            scopeSection,
-            gitSection,
-            constraintsSection,
-            responsibilitiesSection,
-        ].join("\n\n") +
-            selectiveWarning +
-            "\n");
-    }
-    return {
-        claude: build("~/.claude/CLAUDE.md"),
-        opencode: build("~/.config/opencode/AGENTS.md"),
-        codex: build("~/.codex/AGENTS.md"),
-    };
+// --- Shadow label args -------------------------------------------------------------------------------------------------------------------
+function buildShadowLabelArgs(shadowedDirs) {
+    return ["--label", `totopo.shadows=${shadowedDirs.sort().join(",")}`];
 }
-// --- Inject agent context ----------------------------------------------------------------------------------------------------------------
-function injectAgentContext(projectDir, docs) {
-    const a = join(projectDir, "agents");
-    const files = [
-        { path: join(a, "claude", "CLAUDE.md"), content: docs.claude },
-        { path: join(a, "opencode", "config", "AGENTS.md"), content: docs.opencode },
-        { path: join(a, "codex", "AGENTS.md"), content: docs.codex },
-    ];
-    for (const { path: filePath, content } of files) {
-        mkdirSync(dirname(filePath), { recursive: true });
-        writeFileSync(filePath, content);
-    }
+function readContainerShadowLabel(name) {
+    const result = spawnSync("docker", ["inspect", "--format", '{{index .Config.Labels "totopo.shadows"}}', name], {
+        encoding: "utf8",
+        stdio: "pipe",
+    });
+    if (result.status !== 0)
+        return [];
+    const raw = result.stdout.trim();
+    if (!raw || raw === "<no value>")
+        return [];
+    return raw.split(",").sort();
+}
+function shadowsMatch(current, existing) {
+    return JSON.stringify([...current].sort()) === JSON.stringify([...existing].sort());
 }
 // --- Run post-start ----------------------------------------------------------------------------------------------------------------------
 function runPostStart(containerName) {
@@ -429,7 +343,7 @@ function ensureGlobalEnvFile() {
     return envFile;
 }
 // --- Run container -----------------------------------------------------------------------------------------------------------------------
-function runContainer(scope, containerName, imageName, workspaceDir, projectDir, cwd) {
+function runContainer(scope, containerName, imageName, workspaceDir, projectDir, cwd, shadowedDirs) {
     const envFile = ensureGlobalEnvFile();
     const run = spawnSync("docker", [
         "run",
@@ -441,6 +355,7 @@ function runContainer(scope, containerName, imageName, workspaceDir, projectDir,
         envFile,
         ...buildScopeEnvArgs(scope),
         ...buildScopeLabelArgs(scope),
+        ...buildShadowLabelArgs(shadowedDirs),
         "--security-opt",
         "no-new-privileges:true",
         "--label",
@@ -462,6 +377,9 @@ export async function run(_packageDir, ctx) {
     const projectDir = ctx.projectDir;
     // --- Always prompt scope first -------------------------------------------------------------------------------------------------------
     const scope = await promptScope(workspaceDir, cwd);
+    const hostWorkspaceDir = scope.mode === "repo" ? workspaceDir : cwd;
+    const shadowedDirs = resolveShadowedDirs(hostWorkspaceDir);
+    const agentDocs = buildAgentContextDocs(scope, shadowedDirs);
     // --- Inspect container state ---------------------------------------------------------------------------------------------------------
     const inspect = spawnSync("docker", ["inspect", "--format", "{{.State.Status}}", containerName], {
         encoding: "utf8",
@@ -477,17 +395,18 @@ export async function run(_packageDir, ctx) {
             process.exit(build.status ?? 1);
         }
         log.step("Preparing agent context...");
-        injectAgentContext(projectDir, buildAgentContextDocs(scope));
+        injectAgentContext(projectDir, agentDocs);
         log.step("Starting dev container...");
-        runContainer(scope, containerName, imageName, workspaceDir, projectDir, cwd);
+        runContainer(scope, containerName, imageName, workspaceDir, projectDir, cwd, shadowedDirs);
         runPostStart(containerName);
     }
     else if (containerStatus === "exited") {
-        // --- Container stopped - resume or recreate based on scope -----------------------------------------------------------------------
+        // --- Container stopped - resume or recreate based on scope/shadows ---------------------------------------------------------------
         const existingScope = readContainerScopeLabel(containerName);
-        if (scopesMatch(scope, existingScope, workspaceDir)) {
+        const existingShadows = readContainerShadowLabel(containerName);
+        if (scopesMatch(scope, existingScope, workspaceDir) && shadowsMatch(shadowedDirs, existingShadows)) {
             log.step("Preparing agent context...");
-            injectAgentContext(projectDir, buildAgentContextDocs(scope));
+            injectAgentContext(projectDir, agentDocs);
             log.step("Resuming dev container...");
             const start = spawnSync("docker", ["start", containerName], { stdio: "inherit" });
             if (start.status !== 0) {
@@ -498,28 +417,29 @@ export async function run(_packageDir, ctx) {
         }
         else {
             log.step("Preparing agent context...");
-            injectAgentContext(projectDir, buildAgentContextDocs(scope));
+            injectAgentContext(projectDir, agentDocs);
             log.step("Recreating dev container with new scope...");
             removeContainer(containerName);
-            runContainer(scope, containerName, imageName, workspaceDir, projectDir, cwd);
+            runContainer(scope, containerName, imageName, workspaceDir, projectDir, cwd, shadowedDirs);
             runPostStart(containerName);
         }
     }
     else {
-        // --- Container running - connect directly or recreate based on scope -------------------------------------------------------------
+        // --- Container running - connect directly or recreate based on scope/shadows -----------------------------------------------------
         const existingScope = readContainerScopeLabel(containerName);
-        if (!scopesMatch(scope, existingScope, workspaceDir)) {
+        const existingShadows = readContainerShadowLabel(containerName);
+        if (!scopesMatch(scope, existingScope, workspaceDir) || !shadowsMatch(shadowedDirs, existingShadows)) {
             log.step("Preparing agent context...");
-            injectAgentContext(projectDir, buildAgentContextDocs(scope));
+            injectAgentContext(projectDir, agentDocs);
             log.step("Recreating dev container with new scope...");
             removeContainer(containerName);
-            runContainer(scope, containerName, imageName, workspaceDir, projectDir, cwd);
+            runContainer(scope, containerName, imageName, workspaceDir, projectDir, cwd, shadowedDirs);
             runPostStart(containerName);
         }
         else {
-            // Same scope and container already running - refresh context in place.
+            // Same scope/shadows and container already running - refresh context in place.
             log.step("Refreshing agent context...");
-            injectAgentContext(projectDir, buildAgentContextDocs(scope));
+            injectAgentContext(projectDir, agentDocs);
         }
         // Fall through to connect
     }

package/dist/lib/agent-context.js

@@ -0,0 +1,223 @@
+// Agent mount definitions and context injection for AI CLIs running inside totopo containers.
+//
+// This file is the single source of truth for which directories each AI CLI reads/writes
+// and how totopo intercepts them via bind mounts. If an AI CLI changes its config layout,
+// this file must be updated.
+//
+// Verify against official docs periodically:
+//   Claude Code: https://docs.anthropic.com/en/docs/claude-code
+//   OpenCode:    https://github.com/opencode-ai/opencode
+//   Codex:       https://github.com/openai/codex
+//
+// Note: OpenCode also reads `.opencode.json` (a file, not a dir) at the workspace root
+// if the user has one. No shadow is needed - OpenCode never auto-creates this file in
+// the project directory.
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+export const AGENT_MOUNTS = [
+    // Home-dir mounts - user-level AI CLI state
+    {
+        agent: "claude",
+        kind: "home",
+        hostSubpath: "claude",
+        container: "/home/devuser/.claude",
+        description: "Claude Code user-level config and session data",
+    },
+    {
+        agent: "opencode",
+        kind: "home",
+        hostSubpath: "opencode/config",
+        container: "/home/devuser/.config/opencode",
+        description: "OpenCode user-level config",
+    },
+    {
+        agent: "opencode",
+        kind: "home",
+        hostSubpath: "opencode/data",
+        container: "/home/devuser/.local/share/opencode",
+        description: "OpenCode user-level data and session history",
+    },
+    {
+        agent: "codex",
+        kind: "home",
+        hostSubpath: "codex",
+        container: "/home/devuser/.codex",
+        description: "Codex user-level config and session data",
+    },
+    // Workspace shadow mounts - intercept project-level config dirs
+    {
+        agent: "claude",
+        kind: "workspace-shadow",
+        hostSubpath: "workspace/.claude",
+        container: "/workspace/.claude",
+        description: "Shadows project-level .claude/",
+    },
+    {
+        agent: "codex",
+        kind: "workspace-shadow",
+        hostSubpath: "workspace/.codex",
+        container: "/workspace/.codex",
+        description: "Shadows project-level .codex/",
+    },
+    {
+        agent: "opencode",
+        kind: "workspace-shadow",
+        hostSubpath: "workspace/.opencode",
+        container: "/workspace/.opencode",
+        description: "Shadows project-level .opencode/",
+    },
+];
+// --- Shadow resolution -------------------------------------------------------------------------------------------------------------------
+/**
+ * Returns the container paths of workspace-shadow mounts that should be applied.
+ * A shadow is applied when the corresponding directory does NOT exist on the host workspace.
+ * If it exists, the user's real dir passes through via the parent workspace mount.
+ */
+export function resolveShadowedDirs(hostWorkspaceDir) {
+    return AGENT_MOUNTS.filter((m) => m.kind === "workspace-shadow")
+        .filter((m) => !existsSync(join(hostWorkspaceDir, basename(m.container))))
+        .map((m) => m.container);
+}
+// --- Build agent mount args --------------------------------------------------------------------------------------------------------------
+/**
+ * Creates agents/ subdirectories in the project dir on the host (lazily) and
+ * returns volume mount args for all supported agent tools.
+ *
+ * Home-dir mounts are always included. Workspace-shadow mounts are only included
+ * for directories that don't exist on the host workspace (automatic detection).
+ */
+export function buildAgentMountArgs(projectDir, hostWorkspaceDir) {
+    const agentsDir = join(projectDir, "agents");
+    const shadowedDirs = new Set(resolveShadowedDirs(hostWorkspaceDir));
+    const mounts = AGENT_MOUNTS.filter((m) => {
+        if (m.kind === "home")
+            return true;
+        // Only include workspace-shadow mounts for dirs that don't exist on host
+        return shadowedDirs.has(m.container);
+    }).map((m) => ({
+        host: join(agentsDir, m.hostSubpath),
+        container: m.container,
+    }));
+    for (const { host } of mounts)
+        mkdirSync(host, { recursive: true });
+    return mounts.flatMap(({ host, container }) => ["-v", `${host}:${container}`]);
+}
+// --- Build agent context documents -------------------------------------------------------------------------------------------------------
+/**
+ * Assembles the agent context markdown injected into each supported agent's config dir at session start.
+ */
+export function buildAgentContextDocs(scope, shadowedDirs) {
+    // -- Scope section --------------------------------------------------------------------------------------------------------------------
+    let scopeSection;
+    if (scope.mode === "repo") {
+        scopeSection = `## Workspace scope: repo
+
+You have access to the full repository at \`/workspace\`. Some operations (git push, system-level changes) require running on the host.`;
+    }
+    else if (scope.mode === "cwd") {
+        scopeSection = `## Workspace scope: cwd
+
+Workspace is scoped to one directory (\`${scope.hostCwd}\`). Files outside it are not visible to you. Commands that depend on absent files will fail.`;
+    }
+    else {
+        const pathList = scope.selectedPaths.map((p) => `- \`/workspace/${p}\``).join("\n");
+        scopeSection = `## Workspace scope: selective
+
+Workspace is selectively scoped. Only the following paths are mounted:\n\n${pathList}`;
+    }
+    // -- Git section ----------------------------------------------------------------------------------------------------------------------
+    let gitSection;
+    if (scope.mode === "repo") {
+        gitSection = `## Git availability
+
+Git is fully available for local operations (commit, branch, log, diff, status, etc.).
+
+Remote access (push, pull, fetch, clone) is **blocked at the system level** by design — \`protocol.allow = never\` is enforced in \`/etc/gitconfig\` and cannot be overridden without root. This is a deliberate security boundary: the container has no access to remote repositories. Ask the user to run any remote git operations from the host.`;
+    }
+    else {
+        gitSection = `## Git availability
+
+Git local operations are **not available** in this scope — \`.git\` is not mounted. This is intentional: mounting \`.git\` would expose the full commit history of all repository files, including those outside your current mount, defeating the security boundary of scoped access.
+
+Remote access is also **blocked container-wide** by design (\`protocol.allow = never\` in \`/etc/gitconfig\`).
+
+If git operations are needed, ask the user to run them on the host.`;
+    }
+    // -- Selective-only warning -----------------------------------------------------------------------------------------------------------
+    const selectiveWarning = scope.mode === "selective"
+        ? `\n\n## Selective scope: file creation warning
+
+Any file you create **outside your mounted paths** (e.g. at \`/\`, \`/tmp\`, or any path not listed above) will **not be visible on the host** and will be lost when the container is rebuilt.
+
+If the user asks you to create or modify a file at such a location:
+1. Notify the user that the path is outside your mounted workspace.
+2. Explain that files created there will not sync to the host.
+3. Suggest the user run the command on the host instead, or confirm they want the file only inside the container (understanding it will be lost on rebuild).`
+        : "";
+    // -- Workspace config isolation section ------------------------------------------------------------------------------------------------
+    let isolationSection = "";
+    if (shadowedDirs.length > 0) {
+        const dirList = shadowedDirs
+            .sort()
+            .map((d) => `- \`${d}/\` — redirected to totopo's isolated agent storage`)
+            .join("\n");
+        isolationSection = `\n\n## Workspace config isolation
+
+The following workspace directories are shadow-mounted by totopo and do NOT
+correspond to directories in the user's actual project:
+
+${dirList}
+
+Project memory and session state at these paths is stored in \`~/.totopo/\` on
+the host, not in the user's project directory. If the user asks about where
+their AI CLI config or memory is stored, explain this.
+
+Do not mention this at session start — only surface it if the user asks.`;
+    }
+    // -- Responsibilities section ---------------------------------------------------------------------------------------------------------
+    const responsibilitiesSection = `## Your responsibilities at session start
+
+At the start of every session:
+- Briefly surface your current workspace scope and its limitations to the user.
+- Tell the user what you cannot access in this session (files, git, remotes).`;
+    // -- Assemble per-tool - only the self-referencing path differs -----------------------------------------------------------------------
+    function build(toolPath) {
+        const constraintsSection = `## Constraints
+
+- Files outside mounted paths cannot be read, written, or executed.
+- If a command fails because of missing files, tell the user: "I have limited workspace scope — please run \`<command>\` on the host."
+- \`~/.totopo/\` is read-only inside the container.
+- This file (\`${toolPath}\`) is managed by totopo and overwritten on every session start. Do not edit it.`;
+        return ([
+            "# totopo Workspace Context\n\nYou are running inside a totopo dev container.\n",
+            scopeSection,
+            gitSection,
+            constraintsSection,
+            responsibilitiesSection,
+        ].join("\n\n") +
+            selectiveWarning +
+            isolationSection +
+            "\n");
+    }
+    return {
+        claude: build("~/.claude/CLAUDE.md"),
+        opencode: build("~/.config/opencode/AGENTS.md"),
+        codex: build("~/.codex/AGENTS.md"),
+    };
+}
+// --- Inject agent context ----------------------------------------------------------------------------------------------------------------
+/**
+ * Writes agent context markdown files into the project's agents/ directory.
+ */
+export function injectAgentContext(projectDir, docs) {
+    const a = join(projectDir, "agents");
+    const files = [
+        { path: join(a, "claude", "CLAUDE.md"), content: docs.claude },
+        { path: join(a, "opencode", "config", "AGENTS.md"), content: docs.opencode },
+        { path: join(a, "codex", "AGENTS.md"), content: docs.codex },
+    ];
+    for (const { path: filePath, content } of files) {
+        mkdirSync(dirname(filePath), { recursive: true });
+        writeFileSync(filePath, content);
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "totopo",
-  "version": "2.0.0",
+  "version": "2.1.0-rc-2",
   "description": "Run AI coding agents safely in your local codebase",
   "type": "module",
   "bin": {