refactor(process): schema diet — enum names the verbs, description keeps only non-obvious semantics; write-vs-submit trap teaching emphasized (306 -> 228 tok/call, -25%) (#97279)

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()

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
             }
         },