# ADR-0124: Extended Arm Command Parameters (auto_stay_cancel, exit_delay_cancel)

Status: Draft

## Context

The E27 API area.set_arm_state request is used to command arm and disarm state
transitions for an area. The documented request structure includes the fields:

- area_id
- pin
- arm_state

The control panel also supports two additional optional parameters that
influence arming behavior:

- auto_stay_cancel
- exit_delay_cancel

These parameters allow a client to control how the panel handles exit delay
and automatic stay behavior during arming.

Without exposing these parameters, integrations cannot control these behaviors,
which can result in inconsistent arming semantics between different clients
interacting with the panel.

## Decision

The E27 library will extend the canonical area.set_arm_state request structure
to support two additional optional parameters:

- auto_stay_cancel
- exit_delay_cancel

Both parameters default to false.

The canonical request generated by the library becomes:

{
  "seq": <seq>,
  "session_id": <session>,
  "area": {
    "set_arm_state": {
      "area_id": <id>,
      "pin": <pin>,
      "arm_state": "<state>",
      "auto_stay_cancel": false,
      "exit_delay_cancel": false
    }
  }
}

Example request:

{"seq":0,"session_id":0,"area":{"set_arm_state":{"area_id":1,"pin":1729,"arm_state":"ARMED_AWAY","auto_stay_cancel":true,"exit_delay_cancel":true}}}

## Parameter Semantics

auto_stay_cancel

Controls whether the panel automatically transitions to STAY mode if interior
zones are violated during exit.

false (default)
Normal panel behavior is used.

true
Cancels the automatic stay transition behavior.

exit_delay_cancel

Controls whether the exit delay timer should be cancelled when arming.

false (default)
Standard exit delay behavior.

true
Exit delay is cancelled and the system arms immediately.

## Library Responsibilities

The E27 library will:

- expose both parameters in the arm command API
- default both parameters to false
- include the parameters in outbound JSON
- allow callers to override these values when necessary

## Home Assistant Responsibilities

Home Assistant will:

- continue using default behavior (false) unless specific UI or automation
  features require overriding these flags
- treat these parameters as optional enhancements rather than required fields

## Rationale

Explicitly including these parameters:

- ensures consistent command semantics
- exposes the full capability of the control panel
- avoids hidden panel behavior differences
- prevents future API changes from requiring structural changes in the
  integration

Defaulting them to false preserves backward-compatible behavior.

## Consequences

- The arm command builder in the library must be updated to include these
  parameters.
- Existing Home Assistant calls remain compatible because the defaults match
  legacy behavior.
- Future Home Assistant features may expose these flags for advanced arming
  control.

## References

E27 Dealer API documentation – area.set_arm_state
ADR-0124: PIN Field Semantics and Request Taxonomy
ADR-0110: Permission-Aware Command Planning
