Merge branch 'main' into 23740-chat-recording-jsonl-streaming

Author: spencer426

docs/core/subagents.md

@@ -521,6 +521,24 @@ field.
 }
 ```
 
+#### Safety policies (TOML)
+
+You can restrict access to specific subagents using the CLI's **Policy Engine**.
+Subagents are treated as virtual tool names for policy matching purposes.
+
+To govern access to a subagent, create a `.toml` file in your policy directory
+(e.g., `~/.gemini/policies/`):
+
+```toml
+[[rule]]
+toolName = "codebase_investigator"
+decision = "deny"
+deny_message = "Deep codebase analysis is restricted for this session."
+```
+
+For more information on setting up fine-grained safety guardrails, see the
+[Policy Engine reference](../reference/policy-engine.md#special-syntax-for-subagents).
+
 ### Optimizing your subagent
 
 The main agent's system prompt encourages it to use an expert subagent when one

docs/reference/keyboard-shortcuts.md

@@ -91,7 +91,7 @@ available combinations.
 | `input.submit`                       | Submit the current prompt.                                                | `Enter`                                                                             |
 | `input.queueMessage`                 | Queue the current prompt to be processed after the current task finishes. | `Tab`                                                                               |
 | `input.newline`                      | Insert a newline without submitting.                                      | `Ctrl+Enter`<br />`Cmd/Win+Enter`<br />`Alt+Enter`<br />`Shift+Enter`<br />`Ctrl+J` |
-| `input.openExternalEditor`           | Open the current prompt or the plan in an external editor.                | `Ctrl+G`                                                                            |
+| `input.openExternalEditor`           | Open the current prompt or the plan in an external editor.                | `Ctrl+G`<br />`Ctrl+Shift+G`                                                        |
 | `input.deprecatedOpenExternalEditor` | Deprecated command to open external editor.                               | `Ctrl+X`                                                                            |
 | `input.paste`                        | Paste from the clipboard.                                                 | `Ctrl+V`<br />`Cmd/Win+V`<br />`Alt+V`                                              |
 

docs/reference/policy-engine.md

@@ -438,6 +438,33 @@ decision = "ask_user"
 priority = 10
 ```
 
+### Special syntax for subagents
+
+You can secure and govern subagents using standard policy rules by treating the
+subagent's name as the `toolName`.
+
+When the main agent invokes a subagent (e.g., using the unified `invoke_agent`
+tool), the Policy Engine automatically treats the target `agent_name` as a
+virtual tool alias for rule matching.
+
+**Example:**
+
+This rule denies access to the `codebase_investigator` subagent.
+
+```toml
+[[rule]]
+toolName = "codebase_investigator"
+decision = "deny"
+priority = 500
+deny_message = "Deep codebase analysis is restricted for this session."
+```
+
+- **Backward Compatibility**: Any rules written targeting historical 1:1
+  subagent tool names will continue to match transparently.
+- **Context differentiation**: To create rules based on **who** is calling a
+  tool, use the `subagent` field instead. See
+  [TOML rule schema](#toml-rule-schema).
+
 ## Default policies
 
 The Gemini CLI ships with a set of default policies to provide a safe

evals/subagents.eval.ts

@@ -9,10 +9,46 @@ import path from 'node:path';
 
 import { describe, expect } from 'vitest';
 
-import { evalTest, TEST_AGENTS } from './test-helper.js';
+import { AGENT_TOOL_NAME } from '@google/gemini-cli-core';
+import { evalTest, TEST_AGENTS, TestRig } from './test-helper.js';
 
 const INDEX_TS = 'export const add = (a: number, b: number) => a + b;\n';
 
+/**
+ * Helper to verify that a specific subagent was successfully invoked via the unified tool.
+ */
+async function expectSubagentCall(rig: TestRig, agentName: string) {
+  await rig.expectToolCallSuccess(
+    [AGENT_TOOL_NAME],
+    undefined,
+    (args: string) => {
+      try {
+        const parsed = JSON.parse(args);
+        return parsed.agent_name === agentName;
+      } catch {
+        return false;
+      }
+    },
+  );
+}
+
+/**
+ * Helper to check if a subagent (either via unified tool or direct name) was called.
+ */
+function isSubagentCalled(toolLogs: any[], agentName: string): boolean {
+  return toolLogs.some((l) => {
+    if (l.toolRequest.name === AGENT_TOOL_NAME) {
+      try {
+        const args = JSON.parse(l.toolRequest.args);
+        return args.agent_name === agentName;
+      } catch {
+        return false;
+      }
+    }
+    return l.toolRequest.name === agentName;
+  });
+}
+
 // A minimal package.json is used to provide a realistic workspace anchor.
 // This prevents the agent from making incorrect assumptions about the environment
 // and helps it properly navigate or act as if it is in a standard Node.js project.
@@ -62,7 +98,7 @@ describe('subagent eval test cases', () => {
       'README.md': 'TODO: update the README.\n',
     },
     assert: async (rig, _result) => {
-      await rig.expectToolCallSuccess([TEST_AGENTS.DOCS_AGENT.name]);
+      await expectSubagentCall(rig, TEST_AGENTS.DOCS_AGENT.name);
     },
   });
 
@@ -99,14 +135,10 @@ describe('subagent eval test cases', () => {
       }>;
 
       expect(updatedIndex).toContain('export const sum =');
-      expect(
-        toolLogs.some(
-          (l) => l.toolRequest.name === TEST_AGENTS.DOCS_AGENT.name,
-        ),
-      ).toBe(false);
-      expect(toolLogs.some((l) => l.toolRequest.name === 'generalist')).toBe(
+      expect(isSubagentCalled(toolLogs, TEST_AGENTS.DOCS_AGENT.name)).toBe(
         false,
       );
+      expect(isSubagentCalled(toolLogs, 'generalist')).toBe(false);
     },
   });
 
@@ -140,13 +172,11 @@ describe('subagent eval test cases', () => {
     },
     assert: async (rig, _result) => {
       const toolLogs = rig.readToolLogs() as Array<{
-        toolRequest: { name: string };
+        toolRequest: { name: string; args: string };
       }>;
 
-      await rig.expectToolCallSuccess([TEST_AGENTS.TESTING_AGENT.name]);
-      expect(toolLogs.some((l) => l.toolRequest.name === 'generalist')).toBe(
-        false,
-      );
+      await expectSubagentCall(rig, TEST_AGENTS.TESTING_AGENT.name);
+      expect(isSubagentCalled(toolLogs, 'generalist')).toBe(false);
     },
   });
 
@@ -181,18 +211,15 @@ describe('subagent eval test cases', () => {
     },
     assert: async (rig, _result) => {
       const toolLogs = rig.readToolLogs() as Array<{
-        toolRequest: { name: string };
+        toolRequest: { name: string; args: string };
       }>;
       const readme = readProjectFile(rig, 'README.md');
 
-      await rig.expectToolCallSuccess([
-        TEST_AGENTS.DOCS_AGENT.name,
-        TEST_AGENTS.TESTING_AGENT.name,
-      ]);
+      await expectSubagentCall(rig, TEST_AGENTS.DOCS_AGENT.name);
+      await expectSubagentCall(rig, TEST_AGENTS.TESTING_AGENT.name);
+
       expect(readme).not.toContain('TODO: update the README.');
-      expect(toolLogs.some((l) => l.toolRequest.name === 'generalist')).toBe(
-        false,
-      );
+      expect(isSubagentCalled(toolLogs, 'generalist')).toBe(false);
     },
   });
 
@@ -219,14 +246,11 @@ describe('subagent eval test cases', () => {
       'package.json': MOCK_PACKAGE_JSON,
     },
     assert: async (rig, _result) => {
-      const toolLogs = rig.readToolLogs() as Array<{
-        toolRequest: { name: string };
-      }>;
-      await rig.expectToolCallSuccess(['database-agent']);
+      const toolLogs = rig.readToolLogs();
+      await expectSubagentCall(rig, TEST_AGENTS.DATABASE_AGENT.name);
 
       // Ensure the generalist and other irrelevant specialists were not invoked
       const uncalledAgents = [
-        'generalist',
         TEST_AGENTS.DOCS_AGENT.name,
         TEST_AGENTS.TESTING_AGENT.name,
         TEST_AGENTS.CSS_AGENT.name,
@@ -239,10 +263,9 @@ describe('subagent eval test cases', () => {
       ];
 
       for (const agentName of uncalledAgents) {
-        expect(toolLogs.some((l) => l.toolRequest.name === agentName)).toBe(
-          false,
-        );
+        expect(isSubagentCalled(toolLogs, agentName)).toBe(false);
       }
+      expect(isSubagentCalled(toolLogs, 'generalist')).toBe(false);
     },
   });
 
@@ -274,14 +297,11 @@ describe('subagent eval test cases', () => {
       'package.json': MOCK_PACKAGE_JSON,
     },
     assert: async (rig, _result) => {
-      const toolLogs = rig.readToolLogs() as Array<{
-        toolRequest: { name: string };
-      }>;
-      await rig.expectToolCallSuccess(['database-agent']);
+      const toolLogs = rig.readToolLogs();
+      await expectSubagentCall(rig, TEST_AGENTS.DATABASE_AGENT.name);
 
       // Ensure the generalist and other irrelevant specialists were not invoked
       const uncalledAgents = [
-        'generalist',
         TEST_AGENTS.DOCS_AGENT.name,
         TEST_AGENTS.TESTING_AGENT.name,
         TEST_AGENTS.CSS_AGENT.name,
@@ -294,10 +314,9 @@ describe('subagent eval test cases', () => {
       ];
 
       for (const agentName of uncalledAgents) {
-        expect(toolLogs.some((l) => l.toolRequest.name === agentName)).toBe(
-          false,
-        );
+        expect(isSubagentCalled(toolLogs, agentName)).toBe(false);
       }
+      expect(isSubagentCalled(toolLogs, 'generalist')).toBe(false);
     },
   });
 });

integration-tests/browser-agent-localhost.dynamic.responses

@@ -1,4 +1,4 @@
-{"method":"generateContentStream","response":[{"candidates":[{"content":{"parts":[{"text":"I'll check the dynamic content page on the localhost server."},{"functionCall":{"name":"browser_agent","args":{"task":"Navigate to http://127.0.0.1:18923/dynamic.html, wait for the dynamic content to load, then capture the accessibility tree and report what content appeared"}}}],"role":"model"},"finishReason":"STOP","index":0}],"usageMetadata":{"promptTokenCount":100,"candidatesTokenCount":40,"totalTokenCount":140}}]}
+{"method":"generateContentStream","response":[{"candidates":[{"content":{"parts":[{"text":"I'll check the dynamic content page on the localhost server."},{"functionCall":{"name":"invoke_agent","args":{"agent_name":"browser_agent","prompt":"Navigate to http://127.0.0.1:18923/dynamic.html, wait for the dynamic content to load, then capture the accessibility tree and report what content appeared"}}}],"role":"model"},"finishReason":"STOP","index":0}],"usageMetadata":{"promptTokenCount":100,"candidatesTokenCount":40,"totalTokenCount":140}}]}
 {"method":"generateContentStream","response":[{"candidates":[{"content":{"parts":[{"functionCall":{"name":"navigate_page","args":{"url":"http://127.0.0.1:18923/dynamic.html"}}}],"role":"model"},"finishReason":"STOP","index":0}],"usageMetadata":{"promptTokenCount":100,"candidatesTokenCount":20,"totalTokenCount":120}}]}
 {"method":"generateContentStream","response":[{"candidates":[{"content":{"parts":[{"functionCall":{"name":"wait_for","args":{"selector":"#dynamic-content","state":"visible","timeout":5000}}}],"role":"model"},"finishReason":"STOP","index":0}],"usageMetadata":{"promptTokenCount":150,"candidatesTokenCount":25,"totalTokenCount":175}}]}
 {"method":"generateContentStream","response":[{"candidates":[{"content":{"parts":[{"functionCall":{"name":"take_snapshot","args":{}}}],"role":"model"},"finishReason":"STOP","index":0}],"usageMetadata":{"promptTokenCount":180,"candidatesTokenCount":15,"totalTokenCount":195}}]}

integration-tests/browser-agent-localhost.form.responses

@@ -1,4 +1,4 @@
-{"method":"generateContentStream","response":[{"candidates":[{"content":{"parts":[{"text":"I'll fill out the contact form on the localhost server."},{"functionCall":{"name":"browser_agent","args":{"task":"Navigate to http://127.0.0.1:18923/form.html, fill in the name field with 'Test User', the email field with 'test@example.com', the message field with 'Hello World', and submit the form"}}}],"role":"model"},"finishReason":"STOP","index":0}],"usageMetadata":{"promptTokenCount":100,"candidatesTokenCount":50,"totalTokenCount":150}}]}
+{"method":"generateContentStream","response":[{"candidates":[{"content":{"parts":[{"text":"I'll fill out the contact form on the localhost server."},{"functionCall":{"name":"invoke_agent","args":{"agent_name":"browser_agent","prompt":"Navigate to http://127.0.0.1:18923/form.html, fill in the name field with 'Test User', the email field with 'test@example.com', the message field with 'Hello World', and submit the form"}}}],"role":"model"},"finishReason":"STOP","index":0}],"usageMetadata":{"promptTokenCount":100,"candidatesTokenCount":50,"totalTokenCount":150}}]}
 {"method":"generateContentStream","response":[{"candidates":[{"content":{"parts":[{"functionCall":{"name":"navigate_page","args":{"url":"http://127.0.0.1:18923/form.html"}}}],"role":"model"},"finishReason":"STOP","index":0}],"usageMetadata":{"promptTokenCount":100,"candidatesTokenCount":20,"totalTokenCount":120}}]}
 {"method":"generateContentStream","response":[{"candidates":[{"content":{"parts":[{"functionCall":{"name":"fill","args":{"selector":"#name","value":"Test User"}}}],"role":"model"},"finishReason":"STOP","index":0}],"usageMetadata":{"promptTokenCount":150,"candidatesTokenCount":25,"totalTokenCount":175}}]}
 {"method":"generateContentStream","response":[{"candidates":[{"content":{"parts":[{"functionCall":{"name":"fill","args":{"selector":"#email","value":"test@example.com"}}}],"role":"model"},"finishReason":"STOP","index":0}],"usageMetadata":{"promptTokenCount":180,"candidatesTokenCount":25,"totalTokenCount":205}}]}

integration-tests/browser-agent-localhost.multistep.responses

@@ -1,4 +1,4 @@
-{"method":"generateContentStream","response":[{"candidates":[{"content":{"parts":[{"text":"I'll go through the multi-step flow on the localhost server."},{"functionCall":{"name":"browser_agent","args":{"task":"Navigate to http://127.0.0.1:18923/multi-step/step1.html, fill in 'testuser' as the username, click Next, then on step 2 select 'Option B' and click Finish. Report the final result page content."}}}],"role":"model"},"finishReason":"STOP","index":0}],"usageMetadata":{"promptTokenCount":100,"candidatesTokenCount":50,"totalTokenCount":150}}]}
+{"method":"generateContentStream","response":[{"candidates":[{"content":{"parts":[{"text":"I'll go through the multi-step flow on the localhost server."},{"functionCall":{"name":"invoke_agent","args":{"agent_name":"browser_agent","prompt":"Navigate to http://127.0.0.1:18923/multi-step/step1.html, fill in 'testuser' as the username, click Next, then on step 2 select 'Option B' and click Finish. Report the final result page content."}}}],"role":"model"},"finishReason":"STOP","index":0}],"usageMetadata":{"promptTokenCount":100,"candidatesTokenCount":50,"totalTokenCount":150}}]}
 {"method":"generateContentStream","response":[{"candidates":[{"content":{"parts":[{"functionCall":{"name":"navigate_page","args":{"url":"http://127.0.0.1:18923/multi-step/step1.html"}}}],"role":"model"},"finishReason":"STOP","index":0}],"usageMetadata":{"promptTokenCount":100,"candidatesTokenCount":20,"totalTokenCount":120}}]}
 {"method":"generateContentStream","response":[{"candidates":[{"content":{"parts":[{"functionCall":{"name":"fill","args":{"selector":"#username","value":"testuser"}}}],"role":"model"},"finishReason":"STOP","index":0}],"usageMetadata":{"promptTokenCount":150,"candidatesTokenCount":25,"totalTokenCount":175}}]}
 {"method":"generateContentStream","response":[{"candidates":[{"content":{"parts":[{"functionCall":{"name":"click","args":{"selector":"#next-btn"}}}],"role":"model"},"finishReason":"STOP","index":0}],"usageMetadata":{"promptTokenCount":180,"candidatesTokenCount":20,"totalTokenCount":200}}]}

integration-tests/browser-agent-localhost.navigate.responses

@@ -1,4 +1,4 @@
-{"method":"generateContentStream","response":[{"candidates":[{"content":{"parts":[{"text":"I'll navigate to the localhost page and read its content using the browser agent."},{"functionCall":{"name":"browser_agent","args":{"task":"Navigate to http://127.0.0.1:18923/index.html and tell me the page title and list all links on the page"}}}],"role":"model"},"finishReason":"STOP","index":0}],"usageMetadata":{"promptTokenCount":100,"candidatesTokenCount":40,"totalTokenCount":140}}]}
+{"method":"generateContentStream","response":[{"candidates":[{"content":{"parts":[{"text":"I'll navigate to the localhost page and read its content using the browser agent."},{"functionCall":{"name":"invoke_agent","args":{"agent_name":"browser_agent","prompt":"Navigate to http://127.0.0.1:18923/index.html and tell me the page title and list all links on the page"}}}],"role":"model"},"finishReason":"STOP","index":0}],"usageMetadata":{"promptTokenCount":100,"candidatesTokenCount":40,"totalTokenCount":140}}]}
 {"method":"generateContentStream","response":[{"candidates":[{"content":{"parts":[{"functionCall":{"name":"navigate_page","args":{"url":"http://127.0.0.1:18923/index.html"}}}],"role":"model"},"finishReason":"STOP","index":0}],"usageMetadata":{"promptTokenCount":100,"candidatesTokenCount":20,"totalTokenCount":120}}]}
 {"method":"generateContentStream","response":[{"candidates":[{"content":{"parts":[{"functionCall":{"name":"take_snapshot","args":{}}}],"role":"model"},"finishReason":"STOP","index":0}],"usageMetadata":{"promptTokenCount":150,"candidatesTokenCount":20,"totalTokenCount":170}}]}
 {"method":"generateContentStream","response":[{"candidates":[{"content":{"parts":[{"functionCall":{"name":"complete_task","args":{"result":{"success":true,"summary":"Page title is 'Test Fixture - Home'. Found 3 links: Contact Form (/form.html), Multi-Step Flow (/multi-step/step1.html), Dynamic Content (/dynamic.html)."}}}}],"role":"model"},"finishReason":"STOP","index":0}],"usageMetadata":{"promptTokenCount":200,"candidatesTokenCount":40,"totalTokenCount":240}}]}

integration-tests/browser-agent-localhost.screenshot.responses

@@ -1,4 +1,4 @@
-{"method":"generateContentStream","response":[{"candidates":[{"content":{"parts":[{"text":"I'll take a screenshot of the localhost test page."},{"functionCall":{"name":"browser_agent","args":{"task":"Navigate to http://127.0.0.1:18923/index.html and take a screenshot of the page"}}}],"role":"model"},"finishReason":"STOP","index":0}],"usageMetadata":{"promptTokenCount":100,"candidatesTokenCount":35,"totalTokenCount":135}}]}
+{"method":"generateContentStream","response":[{"candidates":[{"content":{"parts":[{"text":"I'll take a screenshot of the localhost test page."},{"functionCall":{"name":"invoke_agent","args":{"agent_name":"browser_agent","prompt":"Navigate to http://127.0.0.1:18923/index.html and take a screenshot of the page"}}}],"role":"model"},"finishReason":"STOP","index":0}],"usageMetadata":{"promptTokenCount":100,"candidatesTokenCount":35,"totalTokenCount":135}}]}
 {"method":"generateContentStream","response":[{"candidates":[{"content":{"parts":[{"functionCall":{"name":"navigate_page","args":{"url":"http://127.0.0.1:18923/index.html"}}}],"role":"model"},"finishReason":"STOP","index":0}],"usageMetadata":{"promptTokenCount":100,"candidatesTokenCount":20,"totalTokenCount":120}}]}
 {"method":"generateContentStream","response":[{"candidates":[{"content":{"parts":[{"functionCall":{"name":"take_screenshot","args":{}}}],"role":"model"},"finishReason":"STOP","index":0}],"usageMetadata":{"promptTokenCount":150,"candidatesTokenCount":15,"totalTokenCount":165}}]}
 {"method":"generateContentStream","response":[{"candidates":[{"content":{"parts":[{"functionCall":{"name":"complete_task","args":{"result":{"success":true,"summary":"Screenshot captured of the localhost test fixture home page showing the heading, navigation links, and footer.","data":{"screenshotTaken":true}}}}}],"role":"model"},"finishReason":"STOP","index":0}],"usageMetadata":{"promptTokenCount":200,"candidatesTokenCount":40,"totalTokenCount":240}}]}