diff --git a/packages/agent-core/src/tools/builtin/collaboration/agent.md b/packages/agent-core/src/tools/builtin/collaboration/agent.md
index ec0533e7ef..e3bfde220d 100644
--- a/packages/agent-core/src/tools/builtin/collaboration/agent.md
+++ b/packages/agent-core/src/tools/builtin/collaboration/agent.md
@@ -9,7 +9,7 @@ Writing the prompt:
 Usage notes:
 - When the task continues earlier work a subagent already did, prefer resuming that agent (pass its `resume` id) over spawning a fresh instance — the resumed agent keeps its prior context.
 - A subagent's result is only visible to you, not to the user. When the user needs to see what a subagent produced, summarize the relevant parts yourself in your own reply.
-- Subagents use a fixed 30-minute timeout. If one times out, resume the same agent instead of starting over.
+- Subagents use a configurable timeout that defaults to 2 hours (set via the `KIMI_SUBAGENT_TIMEOUT_MS` environment variable or `[subagent] timeout_ms` in config.toml). If one times out, resume the same agent instead of starting over.
 
 When NOT to use Agent: skip delegation for trivial work you can do directly — reading a file whose path you already know, searching a small known set of files, or any task that takes only a step or two. Delegation has a context-handoff cost; it pays off only when the task is substantial enough to outweigh it.
 
diff --git a/packages/agent-core/test/tools/agent.test.ts b/packages/agent-core/test/tools/agent.test.ts
index c2c4311346..f0442f762a 100644
--- a/packages/agent-core/test/tools/agent.test.ts
+++ b/packages/agent-core/test/tools/agent.test.ts
@@ -124,12 +124,14 @@ describe('AgentTool', () => {
     expect(properties).not.toHaveProperty('timeout');
   });
 
-  it('explains the fixed background subagent timeout', () => {
+  it('explains the configurable subagent timeout with a 2-hour default', () => {
     const host = mockSubagentHost({ spawn: vi.fn() });
     const tool = agentTool(host);
 
-    expect(tool.description).toContain('fixed 30-minute timeout');
-    expect(tool.description).not.toContain('operator-configured background timeout');
+    expect(tool.description).toContain('configurable timeout');
+    expect(tool.description).toContain('defaults to 2 hours');
+    expect(tool.description).toContain('KIMI_SUBAGENT_TIMEOUT_MS');
+    expect(tool.description).not.toContain('fixed 30-minute timeout');
     expect(tool.description).not.toContain('no time limit');
     // Background guidance must steer foreground-by-default, so the model doesn't
     // background-launch a result it needs and then block waiting on it.