fix(cli): reject unexpected command arguments

Apps/CLI/Sources/PeekabooCLI/Commands/Interaction/HotkeyCommand+CommanderMetadata.swift

@@ -3,6 +3,13 @@ import Commander
 extension HotkeyCommand: CommanderSignatureProviding {
     static func commanderSignature() -> CommandSignature {
         CommandSignature(
+            arguments: [
+                .make(
+                    label: "keys",
+                    help: "Keys to press (comma-, plus-, or space-separated)",
+                    isOptional: true
+                ),
+            ],
             options: [
                 .commandOption(
                     "keys",

Apps/CLI/Tests/CLIRuntimeTests/CLIRuntimeSmokeTests.swift

@@ -116,6 +116,26 @@ struct CLIRuntimeSmokeTests {
         #expect((dataPayload?["count"] as? Int ?? 0) > 0)
     }
 
+    @Test
+    func `peekaboo tools rejects unexpected positional arguments in JSON mode`() async throws {
+        guard Self.ensureLocalRuntimeAvailable() else { return }
+        let result = try await TestChildProcess.runPeekaboo(["tools", "extra", "--json", "--no-remote"])
+        #expect(result.status == .exited(1))
+        #expect(result.standardError.isEmpty)
+
+        let data = Data(result.standardOutput.utf8)
+        let object = try JSONSerialization.jsonObject(with: data)
+        guard let json = object as? [String: Any],
+              let error = json["error"] as? [String: Any] else {
+            Issue.record("Expected JSON parse-error output from tools command.")
+            return
+        }
+
+        #expect(json["success"] as? Bool == false)
+        #expect(error["code"] as? String == "INVALID_ARGUMENT")
+        #expect((error["message"] as? String)?.contains("Unexpected argument: extra") == true)
+    }
+
     @Test
     func `peekaboo commander emits diagnostics JSON`() async throws {
         guard Self.ensureLocalRuntimeAvailable() else { return }

CHANGELOG.md

@@ -162,6 +162,7 @@
 - The docs site now publishes generated documentation pages at the site root and writes the sitemap from the generated page set.
 
 ### Fixed
+- Commander-backed CLI commands without positional arguments now reject unexpected trailing tokens instead of silently ignoring them.
 - Snapshot-backed UIAX actions now preserve app/window context when rehydrating snapshots, so `actionOnly` element clicks resolve in the captured app instead of the frontmost app.
 - `peekaboo click` now accepts the shared `--input-strategy` runtime override so action-only and synth-only paths can be tested directly.
 - `peekaboo click --input-strategy actionOnly` now focuses editable text controls via `AXFocused` when they do not expose `AXPress`, matching Computer Use-style element targeting more closely.

Commander

@@ -1 +1 @@
-Subproject commit ae2ce746b386ff94b26648cfe5625cfa8d02639b
+Subproject commit 2a4c2f830982e7d5d0bb80c0a599e4a5dbe5ea5b