From baa344dee76993f0444c18fc59a69738ccb339d0 Mon Sep 17 00:00:00 2001
From: Teknium <127238744+teknium1@users.noreply.github.com>
Date: Fri, 28 Aug 2026 09:23:00 -0700
Subject: [PATCH] =?UTF-8?q?refactor(process):=20schema=20diet=20=E2=80=94?=
 =?UTF-8?q?=20enum=20names=20the=20verbs,=20description=20keeps=20only=20n?=
 =?UTF-8?q?on-obvious=20semantics;=20write-vs-submit=20trap=20teaching=20e?=
 =?UTF-8?q?mphasized=20(306=20->=20228=20tok/call,=20-25%)=20(#97279)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 tests/tools/test_process_schema_diet.py | 41 +++++++++++++++++++++++++
 tools/process_registry.py               | 25 ++++++++-------
 2 files changed, 55 insertions(+), 11 deletions(-)
 create mode 100644 tests/tools/test_process_schema_diet.py

diff --git a/tests/tools/test_process_schema_diet.py b/tests/tools/test_process_schema_diet.py
new file mode 100644
index 0000000000..7148cca290
--- /dev/null
+++ b/tests/tools/test_process_schema_diet.py
@@ -0,0 +1,41 @@
+"""process schema diet contract (#95681).
+
+Pins the shape: enum names the verbs, description carries only
+non-obvious semantics, and the write-vs-submit trap teaching (Windows
+PTY: a lone newline is not a line terminator) survives with emphasis.
+"""
+import os
+import sys
+import unittest
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..", ".."))
+
+from tools.process_registry import PROCESS_SCHEMA
+
+
+class TestProcessSchemaDiet(unittest.TestCase):
+    def test_write_vs_submit_trap_survives(self):
+        desc = PROCESS_SCHEMA["description"]
+        self.assertIn("submit appends Enter", desc)
+        self.assertIn("answer prompts", desc)
+        self.assertIn("no newline", desc)
+
+    def test_nonobvious_semantics_survive(self):
+        desc = PROCESS_SCHEMA["description"]
+        self.assertIn("partial output on timeout", desc)
+        props = PROCESS_SCHEMA["parameters"]["properties"]
+        self.assertIn("unique prefix", props["session_id"]["description"])
+        self.assertIn("last 200", props["offset"]["description"])
+
+    def test_enum_is_the_verb_source(self):
+        props = PROCESS_SCHEMA["parameters"]["properties"]
+        self.assertEqual(
+            props["action"]["enum"],
+            ["list", "poll", "log", "wait", "kill", "write", "submit", "close"],
+        )
+        # No redundant description on the enum param.
+        self.assertNotIn("description", props["action"])
+
+
+if __name__ == "__main__":
+    unittest.main()
diff --git a/tools/process_registry.py b/tools/process_registry.py
index 6ca23c83aa..bca6f91a05 100644
--- a/tools/process_registry.py
+++ b/tools/process_registry.py
@@ -3243,41 +3243,44 @@ from tools.registry import registry, tool_error
 
 PROCESS_SCHEMA = {
     "name": "process",
+    # Dieted (#95681): the action enum names the verbs; the description
+    # keeps only non-obvious semantics. write-vs-submit is the tool's one
+    # real trap (a lone \n on a Windows PTY is not a line terminator) —
+    # that teaching gains emphasis rather than losing it.
     "description": (
         "Manage background processes started with terminal(background=true). "
-        "Actions: 'list' (show all), 'poll' (check status + new output), "
-        "'log' (full output with pagination), 'wait' (block until done or timeout), "
-        "'kill' (terminate), 'write' (send raw stdin data without newline), "
-        "'submit' (send data + Enter, for answering prompts), 'close' (close stdin/send EOF)."
+        "poll: status + new output. log: full output, paged. wait: block "
+        "until exit or timeout (partial output on timeout). write vs "
+        "submit: submit appends Enter — use it to answer prompts; write "
+        "sends raw bytes, no newline. close: EOF stdin. kill: terminate."
     ),
     "parameters": {
         "type": "object",
         "properties": {
             "action": {
                 "type": "string",
-                "enum": ["list", "poll", "log", "wait", "kill", "write", "submit", "close"],
-                "description": "Action to perform on background processes"
+                "enum": ["list", "poll", "log", "wait", "kill", "write", "submit", "close"]
             },
             "session_id": {
                 "type": "string",
-                "description": "Process session ID (from terminal background output). Required for all actions except 'list'. A unique ID prefix works too (e.g. 'proc_4dae' or just '4dae' for proc_4dae56ca81f6)."
+                "description": "From terminal background output; any unique prefix works ('4dae' for proc_4dae56ca81f6). Required except for 'list'."
             },
             "data": {
                 "type": "string",
-                "description": "Text to send to process stdin (for 'write' and 'submit' actions)"
+                "description": "Stdin text for write/submit."
             },
             "timeout": {
                 "type": "integer",
-                "description": "Max seconds to block for 'wait' action. Returns partial output on timeout.",
+                "description": "Max seconds for 'wait'.",
                 "minimum": 1
             },
             "offset": {
                 "type": "integer",
-                "description": "Line offset for 'log' action (default: last 200 lines)"
+                "description": "Log line offset (default: last 200)."
             },
             "limit": {
                 "type": "integer",
-                "description": "Max lines to return for 'log' action",
+                "description": "Max log lines.",
                 "minimum": 1
             }
         },