Add a pause that holds an agent after its current step

api/openapi.yaml

@@ -1196,6 +1196,36 @@ paths:
         "404": { $ref: "#/components/responses/Error" }
         "409": { $ref: "#/components/responses/Error" }
 
+  /api/sessions/{sessionId}/pause:
+    parameters:
+      - { name: sessionId, in: path, required: true, schema: { type: string } }
+    post:
+      operationId: pauseSession
+      description: Pauses a task agent without interrupting it (see AgentSession.paused).
+      responses:
+        "200":
+          description: The agent is paused.
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/AgentSession" }
+        "404": { $ref: "#/components/responses/Error" }
+        "409": { $ref: "#/components/responses/Error" }
+
+  /api/sessions/{sessionId}/resume:
+    parameters:
+      - { name: sessionId, in: path, required: true, schema: { type: string } }
+    post:
+      operationId: resumeSession
+      description: Ends a pause; messages that queued during it reach the agent now.
+      responses:
+        "200":
+          description: The agent is running again.
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/AgentSession" }
+        "404": { $ref: "#/components/responses/Error" }
+        "409": { $ref: "#/components/responses/Error" }
+
   /api/blobs:
     post:
       operationId: uploadBlob
@@ -2046,7 +2076,7 @@ components:
 
     AgentSession:
       type: object
-      required: [id, task_id, owner, vendor, model, vendor_session_id, state, role, member, created_by, created_at, subagents]
+      required: [id, task_id, owner, vendor, model, vendor_session_id, state, role, member, created_by, created_at, subagents, paused]
       properties:
         id: { type: string }
         task_id: { type: string, description: Empty for a lead session. }
@@ -2065,6 +2095,7 @@ components:
         forked_from: { type: string, description: "A fork's first start resumes this vendor session, cut at forked_at, under a new vendor_session_id; absent for other sessions." }
         forked_at: { type: string, description: "With forked_from: the vendor's id of the last thing the fork keeps, a message for Claude Code, a turn for Codex." }
         subagents: { type: integer, description: "How many of the agent's subagents are running, background ones included after the turn that started them has ended." }
+        paused: { type: boolean, description: "A task agent's pause: mid-turn it holds at its next step (after the tool call or model call in progress finishes); idle, no turn starts and messages queue until resumed." }
     SessionCreate:
       type: object
       required: [prompt]