core: correct sandboxed shell tool description (reads allowed anywhere) (#3069)

Correct the `shell` tool description for sandboxed runs and add targeted
tests.

- Fix the WorkspaceWrite description to clearly state that writes
outside the writable roots require escalated permissions; reads are not
restricted. The previous wording/formatting could be read as restricting
reads outside the workspace.
- Render the writable roots list on its own lines under a newline after
"writable roots:" for clarity.
- Show the "Commands that require network access" note only in
WorkspaceWrite when network is disabled.
- Add focused tests that call `create_shell_tool_for_sandbox` directly
and assert the exact description text for WorkspaceWrite, ReadOnly, and
DangerFullAccess.
- Update AGENTS.md to note that `just fmt` can be run automatically
without asking.

codex-rs/core/src/openai_tools.rs

@@ -240,15 +240,17 @@ fn create_shell_tool_for_sandbox(sandbox_policy: &SandboxPolicy) -> OpenAiTool {
     let description = match sandbox_policy {
         SandboxPolicy::WorkspaceWrite {
             network_access,
+            writable_roots,
             ..
         } => {
             format!(
                 r#"
 The shell tool is used to execute shell commands.
-- When invoking the shell tool, your call will be running in a landlock sandbox, and some shell commands will require escalated privileges:
+- When invoking the shell tool, your call will be running in a sandbox, and some shell commands will require escalated privileges:
   - Types of actions that require escalated privileges:
-    - Reading files outside the current directory
-    - Writing files outside the current directory, and protected folders like .git or .env{}
+    - Writing files other than those in the writable roots
+      - writable roots:
+{}{}
   - Examples of commands that require escalated privileges:
     - git commit
     - npm install or pnpm install
@@ -257,8 +259,9 @@ The shell tool is used to execute shell commands.
 - When invoking a command that will require escalated privileges:
   - Provide the with_escalated_permissions parameter with the boolean value true
   - Include a short, 1 sentence explanation for why we need to run with_escalated_permissions in the justification parameter."#,
+                writable_roots.iter().map(|wr| format!("        - {}", wr.to_string_lossy())).collect::<Vec<String>>().join("\n"),
                 if !network_access {
-                    "\n  - Commands that require network access\n"
+                    "\n    - Commands that require network access\n"
                 } else {
                     ""
                 }
@@ -270,9 +273,8 @@ The shell tool is used to execute shell commands.
         SandboxPolicy::ReadOnly => {
             r#"
 The shell tool is used to execute shell commands.
-- When invoking the shell tool, your call will be running in a landlock sandbox, and some shell commands (including apply_patch) will require escalated permissions:
+- When invoking the shell tool, your call will be running in a sandbox, and some shell commands (including apply_patch) will require escalated permissions:
   - Types of actions that require escalated privileges:
-    - Reading files outside the current directory
     - Writing files
     - Applying patches
   - Examples of commands that require escalated privileges:
@@ -1081,4 +1083,84 @@ mod tests {
             })
         );
     }
+
+    #[test]
+    fn test_shell_tool_for_sandbox_workspace_write() {
+        let sandbox_policy = SandboxPolicy::WorkspaceWrite {
+            writable_roots: vec!["workspace".into()],
+            network_access: false,
+            exclude_tmpdir_env_var: false,
+            exclude_slash_tmp: false,
+        };
+        let tool = super::create_shell_tool_for_sandbox(&sandbox_policy);
+        let OpenAiTool::Function(ResponsesApiTool {
+            description, name, ..
+        }) = &tool
+        else {
+            panic!("expected function tool");
+        };
+        assert_eq!(name, "shell");
+
+        let expected = r#"
+The shell tool is used to execute shell commands.
+- When invoking the shell tool, your call will be running in a sandbox, and some shell commands will require escalated privileges:
+  - Types of actions that require escalated privileges:
+    - Writing files other than those in the writable roots
+      - writable roots:
+        - workspace
+    - Commands that require network access
+
+  - Examples of commands that require escalated privileges:
+    - git commit
+    - npm install or pnpm install
+    - cargo build
+    - cargo test
+- When invoking a command that will require escalated privileges:
+  - Provide the with_escalated_permissions parameter with the boolean value true
+  - Include a short, 1 sentence explanation for why we need to run with_escalated_permissions in the justification parameter."#;
+        assert_eq!(description, expected);
+    }
+
+    #[test]
+    fn test_shell_tool_for_sandbox_readonly() {
+        let tool = super::create_shell_tool_for_sandbox(&SandboxPolicy::ReadOnly);
+        let OpenAiTool::Function(ResponsesApiTool {
+            description, name, ..
+        }) = &tool
+        else {
+            panic!("expected function tool");
+        };
+        assert_eq!(name, "shell");
+
+        let expected = r#"
+The shell tool is used to execute shell commands.
+- When invoking the shell tool, your call will be running in a sandbox, and some shell commands (including apply_patch) will require escalated permissions:
+  - Types of actions that require escalated privileges:
+    - Writing files
+    - Applying patches
+  - Examples of commands that require escalated privileges:
+    - apply_patch
+    - git commit
+    - npm install or pnpm install
+    - cargo build
+    - cargo test
+- When invoking a command that will require escalated privileges:
+  - Provide the with_escalated_permissions parameter with the boolean value true
+  - Include a short, 1 sentence explanation for why we need to run with_escalated_permissions in the justification parameter"#;
+        assert_eq!(description, expected);
+    }
+
+    #[test]
+    fn test_shell_tool_for_sandbox_danger_full_access() {
+        let tool = super::create_shell_tool_for_sandbox(&SandboxPolicy::DangerFullAccess);
+        let OpenAiTool::Function(ResponsesApiTool {
+            description, name, ..
+        }) = &tool
+        else {
+            panic!("expected function tool");
+        };
+        assert_eq!(name, "shell");
+
+        assert_eq!(description, "Runs a shell command and returns its output.");
+    }
 }