Warp Control CLI v2: contract and spec sync by zachlloyd · Pull Request #11772 · warpdotdev/warp

zachlloyd · 2026-05-27T20:13:36Z

Description

Root branch of the Warp Control CLI v2 review stack.

This PR establishes the contract, security model, and first working slice for controlling a running Warp instance through the standalone warpctrl CLI. Major components include:

A shared typed local-control protocol and exact-action allowlist used by both the app and CLI.
The initial warpctrl command surface for instance discovery, app metadata, tab creation, structured output, and shell completions.
An app-side control bridge with deterministic targeting, typed handlers, and exact-action authorization.
Per-instance filesystem discovery, an owner-authenticated Unix credential broker, and an authenticated loopback HTTP request path.
A protected Settings > Scripting enablement model, including isolated owner-only Linux fallback storage for the local-control setting.
Product, technical, and security specs describing the current foundation, trust boundaries, and requirements for future catalog expansion.

The latest update simplifies credentials to authorize one exact action, clarifies the relationship between discovery records, broker sockets, and HTTP endpoints, and keeps the stronger Linux fallback behavior isolated from existing secure-storage consumers.

Demo: https://www.loom.com/share/03740b8c7c40400f9c36eec41d8befca
PR walkthrough: https://www.loom.com/share/b97c3204dcf04dac850aade7d596cc21
Walkthrough URL: https://e94574b9.warp-pr-walkthroughs.pages.dev/

Linked Issue

The linked issue is labeled ready-to-spec or ready-to-implement.
Where appropriate, screenshots or a short video of the implementation are included above.

Testing

Screenshots / Videos

Demo and walkthrough links are included above.

Agent Mode

Warp Agent Mode - This PR was created and updated via Warp's AI Agent Mode

Warp Agent artifacts

Conversation: https://staging.warp.dev/conversation/8a7dca3a-a416-4378-bd49-f19fb78d6e2e

Co-Authored-By: Oz oz-agent@warp.dev

…#11483) ## Description Fix a pre-existing compile error in `app/src/pane_group/mod_tests.rs` that breaks every Warp CI job that builds the `warp` test binary (`Formatting + Clippy (MacOS / Linux / Windows)` and the `Run *Tests` jobs). The call site in `test_entering_remote_parent_agent_view_lazily_restores_local_hidden_child_pane` was passing 4 arguments to `request_ambient_agent_task_id_for_hidden_child`, but the helper at `app/src/pane_group/mod_tests.rs:574` only takes 3 (`panes`, `child_pane_id`, `ctx`). The stray `local_child_conversation_id` argument was added in #10794 and isn't part of the signature, so `rustc` rejects it with E0061. The two other in-tree call sites already use the correct 3-arg shape. This is currently masking CI on every open PR that triggers Warp CI (e.g. #11479's `dependabot/cargo/openssl-0.10.80`). The fix is the exact removal `rustc` itself suggests. Diagnosis context: [conversation](https://staging.warp.dev/conversation/7e6b9f40-55c9-4235-bc3c-1a5424213cc4), [plan](https://staging.warp.dev/drive/notebook/kmgJ7rLA29QP3bvmIzBNS6). ## Linked Issue None — this is a bare compile-fix for a regression in test code introduced by #10794. ## Testing Validated locally in a worktree off `origin/master`: - `cargo fmt --all -- --check` — clean. - `cargo check -p warp --tests` — succeeds (previously failed with E0061). - `cargo clippy --locked -p warp --tests --all-targets -- -D warnings` — succeeds. (Workspace-wide clippy hit an unrelated local `command-signatures-v2` build-script error tied to a `corepack`/`yarn` mismatch in my environment, not introduced by this change; CI will exercise the full workspace.) - [x] I have manually tested my changes locally with `cargo check`/`cargo clippy` (no runtime behavior changes — this is a test-only call-site fix). ## Agent Mode - [x] Warp Agent Mode - This PR was created via Warp's AI Agent Mode  Co-Authored-By: Oz <oz-agent@warp.dev> Co-authored-by: Oz <oz-agent@warp.dev>

Product spec defines the allowlisted local-control CLI with hierarchical selectors, action catalog, 4-tier classification model (read-only metadata, read-only terminal data, non-destructive mutation, destructive/high-risk), differentiated agent vs human permission policies, protocol-first settings, and future extensibility for files and Warp Drive objects. Tech spec covers protocol envelope, per-process discovery, local auth, ModelSpawner bridge architecture, target resolution, CLI library constraints (clap/serde matching Oz CLI), and packaging model. README documents packaging, install/invocation, end-to-end test flow, security model, and authenticated request flow. Co-Authored-By: Oz <oz-agent@warp.dev>

Co-Authored-By: Oz <oz-agent@warp.dev>

Remove local file content operations from the warpctrl public catalog, narrow file/path support to app-state intents, and add the v0 Warp Drive sharing paths for opening the share dialog and sharing personal objects to the current team. Co-Authored-By: Oz <oz-agent@warp.dev>

Co-Authored-By: Oz <oz-agent@warp.dev>

oz-for-oss · 2026-05-28T00:02:37Z

@zachlloyd

I'm starting a first review of this pull request.

You can view the conversation on Warp.

I completed the review and no human review was requested for this pull request.

Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).

Powered by Oz

oz-for-oss

Overview

This PR adds the Warp local-control protocol crate, app-side local-control server/bridge, warpctrl CLI skeleton, Settings > Scripting mode, packaging hooks, and synced Warp Control CLI specs.

Concerns

The wire request shape implemented by the shared protocol does not match the TECH contract example, so external clients built from the synced spec would send requests the app cannot deserialize.
The tab.create resolver falls back to the sole window when no active window exists, contradicting the stated mutating-targeting rule to fail instead of silently retargeting.
No additional security findings beyond the inline contract/targeting issues.

Verdict

Found: 0 critical, 2 important, 0 suggestions

Request changes

Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).

Powered by Oz

oz-for-oss · 2026-05-28T00:08:35Z

+    pub request_id: Uuid,
+    #[serde(default)]
+    pub target: TargetSelector,
+    pub action: Action,


⚠️ [IMPORTANT] The wire shape here nests kind/params under action, but TECH.md documents action and params as top-level fields; clients built from the synced contract will fail to deserialize. Align the serde shape or update the contract before marking this synced.

Addressed in ed284890 and propagated through the zach/warp-cli-v2/* stack. TECH.md now documents the implemented RequestEnvelope / Action serde shape, with action.kind and action.params nested under action, and also updates the response examples to match the tagged ResponseEnvelope / ControlResponse implementation.

oz-for-oss · 2026-05-28T00:08:35Z

+    let window_ids = ctx.window_ids().collect::<Vec<_>>();
+    match window_ids.as_slice() {
+        [window_id] => Ok(*window_id),


⚠️ [IMPORTANT] This fallback silently targets the only window when no active window exists; the tech spec says mutating defaults must return missing_target instead of falling back. Otherwise tab.create can mutate a window the caller did not explicitly select.

Addressed in 88b0bd79 and propagated through the zach/warp-cli-v2/* stack. We kept the implemented resolver behavior and updated PRODUCT.md, SECURITY.md, and TECH.md to document it: an omitted or active window selector first uses the active Warp window, may fall back to the sole existing window when that is the only deterministic target, returns missing_target when no window exists, and returns ambiguous_target when multiple windows exist with no active window.

Co-Authored-By: Oz <oz-agent@warp.dev>

Legoben

only looked thru README.md and SECURITY.md - seems overall good to me but with many footguns if something is off in implementation

alokedesai · 2026-05-28T19:51:24Z

+Warp already has rich interactive actions, but they are primarily reachable through UI, keybindings, menus, or deeplinks. Agents can use native tools for files, code, shell commands, MCP calls, and many context reads, but they cannot reliably operate Warp's own product surfaces: arranging the user's workspace, focusing the correct pane, opening Warp Drive objects, presenting settings, or recovering from ambiguous UI state. Developers also cannot reliably compose those same actions into shell scripts, demos, automation, or agent workflows, and there is no general local protocol for addressing a specific running Warp instance, window, pane, session, terminal block, Warp Drive object, or other uniquely named Warp entity.
+## Goals / Non-goals
+Goals:
+- Provide a first-class, scriptable standalone `warpctrl` binary for controlling running Warp app processes.


Biggest feedback from reading the product / tech spec is that I think creating a separate binary for warpctrl is probably not right.

It's going to cause distribution headaches . Users will either have to download a separate binary or we'll have to bundle the binary as an additional resource in our existing app bundle and then put it on the right path

We have to make the protocol version and channel agnostic, which makes the protocol more complicated than it needs to be.

Can we just bundle this into the existing Warp CLI binary? Similar to how we set up oz as a wrapper script that just calls out to the actual warp binary, we can expose a warpctrl script that does the same thing but with a special --warpctrl flag to differentiate between the two

@bnavetta for this thoughts

i didn't realize that's how oz worked.

my only concern with that approach is around potential latency of spawning a full warp process on every invocation. if that's not an issue in practice, i def agree with doing this the same way as oz (and that was in fact my intention, it's a pretty big miss that it wasn't done that way)

Yeah, I think bundling into the existing binary makes sense.

Latency shouldn't be an issue - the CLI is set up so it doesn't have to fully bootstrap the app for commands that don't need it. For example, oz dump-debug-info is more-or-less instantaneous, while oz whoami is slower because it bootstraps the app and checks auth state on the server.

perfect. super helpful!

Co-Authored-By: Oz <oz-agent@warp.dev>

Add hidden --warpctrl control-mode dispatch through the existing Warp app binary and remove the standalone warpctrl Rust entrypoints. Co-Authored-By: Oz <oz-agent@warp.dev>

Co-Authored-By: Oz <oz-agent@warp.dev>

zachlloyd · 2026-06-03T23:36:56Z

[Warp Agent] Re: #11772 (review) — agreed. The implementation has a lot of security-sensitive footguns if it drifts from the specs, so we are validating that the implementation matches the spec, including using the validate-implementation-matches-spec skill from common-skills.

Co-Authored-By: Oz <oz-agent@warp.dev>

princepal9120 and others added 30 commits May 27, 2026 13:15

fix: point OSS desktop entry at package launcher (#9424)

d05dd49

Address warpctrl spec review feedback

ac892c9

Co-Authored-By: Oz <oz-agent@warp.dev>

Add warpctrl security architecture documentation

86612f3

Co-Authored-By: Oz <oz-agent@warp.dev>

Update warpctrl security enablement model

4dc7cc1

Co-Authored-By: Oz <oz-agent@warp.dev>

Update warpctrl permission model

e4bb06b

Co-Authored-By: Oz <oz-agent@warp.dev>

Add warpctrl scripting enablement settings

2151b02

Co-Authored-By: Oz <oz-agent@warp.dev>

Update warpctrl permission taxonomy specs

6b9f0db

Co-Authored-By: Oz <oz-agent@warp.dev>

Add warpctrl CLI verification plan

2464e44

Co-Authored-By: Oz <oz-agent@warp.dev>

Specify warpctrl target selectors

e8d2e84

Co-Authored-By: Oz <oz-agent@warp.dev>

Document authoritative warpctrl specs branch

270bd71

Co-Authored-By: Oz <oz-agent@warp.dev>

Update warpctrl specs for targeting and security scope

2ff71ac

Co-Authored-By: Oz <oz-agent@warp.dev>

Add WarpCtrlBehavior review gate to warpctrl tech spec

6286aa1

Co-Authored-By: Oz <oz-agent@warp.dev>

Update warpctrl tech plan for reviewable branch stack

c4fde66

Co-Authored-By: Oz <oz-agent@warp.dev>

Create warpctrl core foundation branch

cc48d49

Co-Authored-By: Oz <oz-agent@warp.dev>

Tighten warpctrl foundation gates

e05f824

Co-Authored-By: Oz <oz-agent@warp.dev>

Document combined warpctrl stack base

338856e

Co-Authored-By: Oz <oz-agent@warp.dev>

Document warpctrl core surfaces

7d997e6

Co-Authored-By: Oz <oz-agent@warp.dev>

Address warpctrl foundation review feedback

bed8ee0

Co-Authored-By: Oz <oz-agent@warp.dev>

Clarify warpctrl outside-Warp foundation

a5be127

Co-Authored-By: Oz <oz-agent@warp.dev>

Expand warpctrl authenticated scripting spec

a8a0957

Co-Authored-By: Oz <oz-agent@warp.dev>

Sync warpctrl contract stance

f5e8795

Co-Authored-By: Oz <oz-agent@warp.dev>

Document warpctrl spec ownership invariant

64985cf

Co-Authored-By: Oz <oz-agent@warp.dev>

Restore canonical warpctrl specs

5dcf32c

Co-Authored-By: Oz <oz-agent@warp.dev>

Update warpctrl v2 branch architecture

4d6d80c

Co-Authored-By: Oz <oz-agent@warp.dev>

Update warpctrl screenshot verification guidance

21b07e5

Co-Authored-By: Oz <oz-agent@warp.dev>

Clarify warpctrl visual validation requirements

d26ed03

Co-Authored-By: Oz <oz-agent@warp.dev>

Clarify warpctrl catalog parser parity

138ada9

Co-Authored-By: Oz <oz-agent@warp.dev>

zachlloyd requested a review from Legoben May 28, 2026 00:02

oz-for-oss Bot reviewed May 28, 2026

View reviewed changes

zachlloyd and others added 3 commits May 27, 2026 18:50

Align warpctrl TECH protocol envelope

ed28489

Co-Authored-By: Oz <oz-agent@warp.dev>

Document warpctrl active window fallback

88b0bd7

Co-Authored-By: Oz <oz-agent@warp.dev>

Ignore generated local publish artifacts

67f1cd7

Co-Authored-By: Oz <oz-agent@warp.dev>

Legoben reviewed May 28, 2026

View reviewed changes

alokedesai reviewed May 29, 2026

View reviewed changes

zachlloyd and others added 6 commits May 29, 2026 14:02

Update warpctrl specs for wrapper architecture

a312e79

Co-Authored-By: Oz <oz-agent@warp.dev>

Route warpctrl through Warp binary

b97aa90

Add hidden --warpctrl control-mode dispatch through the existing Warp app binary and remove the standalone warpctrl Rust entrypoints. Co-Authored-By: Oz <oz-agent@warp.dev>

Harden warpctrl local-control security

ff18b06

Co-Authored-By: Oz <oz-agent@warp.dev>

Update common skills lock

775601c

Co-Authored-By: Oz <oz-agent@warp.dev>

Align warpctrl specs with first slice implementation

7761166

Co-Authored-By: Oz <oz-agent@warp.dev>

Polish warpctrl CLI settings row

2c62160

Co-Authored-By: Oz <oz-agent@warp.dev>

alokedesai approved these changes Jun 1, 2026

View reviewed changes

Comment thread specs/warp-control-cli/TECH.md

Comment thread app/src/local_control/handlers/metadata.rs Outdated

Comment thread crates/local_control/src/catalog.rs Outdated

Comment thread script/macos/bundle Outdated

Legoben reviewed Jun 2, 2026

View reviewed changes

bnavetta mentioned this pull request Jun 2, 2026

Centralize build feature profiles in Cargo metadata #11103

Open

Address warpctrl review feedback

6bc74d3

Co-Authored-By: Oz <oz-agent@warp.dev>

zachlloyd and others added 4 commits June 5, 2026 09:37

Align Warp Control CLI implementation with specs

becf4db

Co-Authored-By: Oz <oz-agent@warp.dev>

Close warpctrl contract validation gaps

f480b10

Co-Authored-By: Oz <oz-agent@warp.dev>

Fix warpctrl broker startup context

7542919

Co-Authored-By: Oz <oz-agent@warp.dev>

Merge master into zach/warp-cli-v2/contract-spec-sync

8a3de20

Co-Authored-By: Oz <oz-agent@warp.dev>

Legoben approved these changes Jun 5, 2026

View reviewed changes

zachlloyd and others added 2 commits June 5, 2026 17:02

Refine warpctrl authorization and discovery security

a02831a

Co-Authored-By: Oz <oz-agent@warp.dev>

Fix local control cross-platform compilation

8d9da23

Co-Authored-By: Oz <oz-agent@warp.dev>

zachlloyd enabled auto-merge (squash) June 6, 2026 17:16

Fix Windows local-control CI failures

c6185d2

Co-Authored-By: Oz <oz-agent@warp.dev>

zachlloyd merged commit 5967abf into master Jun 6, 2026
25 checks passed

zachlloyd deleted the zach/warp-cli-v2/contract-spec-sync branch June 6, 2026 18:02

Conversation

zachlloyd commented May 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Linked Issue

Testing

Screenshots / Videos

Agent Mode

Warp Agent artifacts

Uh oh!

oz-for-oss Bot commented May 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

oz-for-oss Bot left a comment

Choose a reason for hiding this comment

Overview

Concerns

Verdict

Uh oh!

oz-for-oss Bot May 28, 2026

Choose a reason for hiding this comment

Uh oh!

zachlloyd May 28, 2026

Choose a reason for hiding this comment

Uh oh!

oz-for-oss Bot May 28, 2026

Choose a reason for hiding this comment

Uh oh!

zachlloyd May 28, 2026

Choose a reason for hiding this comment

Uh oh!

Legoben left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

alokedesai May 28, 2026

Choose a reason for hiding this comment

Uh oh!

zachlloyd May 29, 2026

Choose a reason for hiding this comment

Uh oh!

bnavetta May 29, 2026

Choose a reason for hiding this comment

Uh oh!

zachlloyd May 29, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

zachlloyd commented Jun 3, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

zachlloyd commented May 27, 2026 •

edited

Loading

oz-for-oss Bot commented May 28, 2026 •

edited

Loading