@agenticprimitives/contracts 0.1.0-alpha.2

package/src/enforcers/ValueEnforcer.AUDIT.md

@@ -0,0 +1,51 @@
+# `ValueEnforcer` — Security & Architecture Audit
+
+**Status:** shipped
+**Last refreshed:** 2026-05-21
+**Owners:** delegation package CODEOWNERS
+**Registry entry:** [`docs/architecture/enforcer-registry/enforcers.json`](../../../../docs/architecture/enforcer-registry/enforcers.json) (entry: `ValueEnforcer`)
+**Live address (Base Sepolia):** `0x49F0B31bf5228B1964dED8DC0F357f104cA74523`
+
+## 1. Charter
+
+Caps the native-token (`msg.value`) sent in a redemption to at most `maxValue` wei. Per-call, not cumulative. The redeemer cannot exceed — enforcer reverts.
+
+Does NOT do: cumulative-across-redemptions value caps (DTK splits this into a separate enforcer; we don't have it yet — phase 8). Does not cover ERC-20 token amounts (those live in calldata; phase 6c.6 `ArgumentRuleEnforcer` covers them).
+
+## 2. Security invariants
+
+- `maxValue` is set at delegation creation, immutable.
+- The redemption's `value` parameter is checked exactly: `require(value <= maxValue)`.
+- `maxValue = 0` is permitted (no native-token transfers allowed via this delegation).
+- The check has no slack / decimal logic — bare wei comparison.
+
+## 3. Threat model
+
+| Threat | Likelihood | Impact | Mitigation | Status |
+| --- | --- | --- | --- | --- |
+| Multiple redemptions add up to a value exceeding intent | High by design | High | Per-call only; the delegator MUST add a usage-counter caveat (planned RateLimitEnforcer) for cumulative caps | **Open: VE-1** — cumulative variant tracked as gap |
+| Native-token forwarding from target to other recipients | Low | Medium | Out-of-scope here — the enforcer doesn't trace where the target sends the value. Use `AllowedTargetsEnforcer` to restrict who receives. | By design |
+| `maxValue` set very high accidentally | Low | High | SDK lint should warn above 1 ETH; AgentAccount's `t3HighValueCeiling` provides a second backstop | **Open: VE-2** — lint pending |
+
+## 4. DTK / smart-agent parity
+
+**DTK:** `ValueLteEnforcer` + `NativeTokenLimitEnforcer` split. Our single `ValueEnforcer` matches `ValueLteEnforcer` semantically. We lack the cumulative variant — phase 8.
+
+**smart-agent:** `ValueEnforcer.sol` — same shape.
+
+## 5. Test posture
+
+Forge tests: `packages/contracts/test/Enforcers.t.sol` covers value=maxValue / value<maxValue / value>maxValue / value=0 cases (4 tests).
+
+## 6. Open findings
+
+| ID | Severity | Finding | Status |
+| --- | --- | --- | --- |
+| VE-1 | P2 | No cumulative-value enforcer yet; intent leakage if delegator doesn't pair with RateLimitEnforcer. | Open (phase 8) |
+| VE-2 | P3 | SDK lint warning for high `maxValue` (> 1 ETH) absent. | Open |
+
+## 7. Cross-references
+
+- [Registry entry](../../../../docs/architecture/enforcer-registry/enforcers.json)
+- Spec 207 § 6 — T3 high-value gate that informs how T3 (value) delegations should always carry a ValueEnforcer.
+- Phase 8 follow-up: cumulative-value variant.

package/src/enforcers/ValueEnforcer.sol

@@ -0,0 +1,41 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.28;
+
+import "../agency/ICaveatEnforcer.sol";
+
+/**
+ * @title ValueEnforcer
+ * @notice Enforces a maximum ETH value per call.
+ * @dev terms = abi.encode(uint256 maxValue)
+ *      Follows ERC-7710 / MetaMask DeleGator beforeHook/afterHook pattern.
+ */
+contract ValueEnforcer is ICaveatEnforcer {
+    error ValueExceedsLimit();
+
+    function beforeHook(
+        bytes calldata terms,
+        bytes calldata,
+        bytes32,
+        address,
+        address,
+        address,
+        uint256 value,
+        bytes calldata
+    ) external pure override {
+        uint256 maxValue = abi.decode(terms, (uint256));
+        if (value > maxValue) revert ValueExceedsLimit();
+    }
+
+    function afterHook(
+        bytes calldata,
+        bytes calldata,
+        bytes32,
+        address,
+        address,
+        address,
+        uint256,
+        bytes calldata
+    ) external pure override {
+        // No post-execution check needed
+    }
+}

package/src/governance/AgenticGovernance.sol

@@ -0,0 +1,140 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.28;
+
+import "./IGovernance.sol";
+
+/**
+ * @title AgenticGovernance
+ * @notice H7-C.9 / EXT3-009 closure — the governance surface every
+ *         `GovernanceManaged` contract (`AgentAccountFactory`,
+ *         `SmartAgentPaymaster`, the registries) sees as its
+ *         `governance` immutable. Wraps:
+ *
+ *           - **Pause / unpause** (the kill-switch behind every
+ *             `whenNotPaused` modifier in `GovernanceManaged`).
+ *           - **Forwarded execution** (`execute(target, data, value)`)
+ *             so the slow-path timelock can deliver `onlyGovernance`
+ *             calls that authenticate as `msg.sender == address(this)`.
+ *           - **Signer / pauser registry** (`isSigner`) consumed by
+ *             `IGovernanceView`.
+ *
+ *         Two-role authority split:
+ *           - `timelock` — the OZ `TimelockController(24h)` deployed
+ *             alongside this contract. Owns slow / deliberate actions
+ *             (admin role mutations, unpause, signer changes,
+ *             forwarded calls). All actions go through 24h delay.
+ *           - `guardian` — fast-path emergency pause. CAN pause (no
+ *             delay; the incident-response lever) but CANNOT unpause —
+ *             unpause requires the timelock so an attacker who steals
+ *             guardian keys can't unpause a paused system.
+ *
+ *         Post-deploy operator step (see deploy-runbook): replace the
+ *         bootstrap `[deployer]` proposers/executors on the timelock
+ *         with a long-lived multisig (an `AgentAccount` deployed by
+ *         the factory whose `CustodyPolicy` requires M-of-N signers).
+ *         Deployer then renounces the timelock admin role and is gone.
+ */
+contract AgenticGovernance is IGovernanceView {
+    // ─── Immutables ───────────────────────────────────────────────
+
+    /// @notice The `TimelockController(24h)` that may execute slow-path
+    ///         governance actions through this contract. Set once at
+    ///         construction; rotate by redeploying.
+    address public immutable timelock;
+
+    /// @notice Fast-path emergency-pauser role. Can pause without delay
+    ///         but CANNOT unpause (unpause requires the timelock).
+    address public immutable guardian;
+
+    // ─── State ────────────────────────────────────────────────────
+
+    bool private _paused;
+    mapping(address => bool) private _signers;
+
+    // ─── Errors ───────────────────────────────────────────────────
+
+    error NotTimelock(address caller);
+    error NotGuardian(address caller);
+    error ExecuteFailed(address target, bytes returndata);
+    error ZeroAddress();
+
+    // ─── Events ───────────────────────────────────────────────────
+
+    event Paused(address indexed by);
+    event Unpaused(address indexed by);
+    event SignerSet(address indexed who, bool isSigner);
+    event Executed(address indexed target, uint256 value, bytes data);
+
+    // ─── Constructor ──────────────────────────────────────────────
+
+    constructor(address timelock_, address guardian_, address[] memory initialSigners) {
+        if (timelock_ == address(0) || guardian_ == address(0)) revert ZeroAddress();
+        timelock = timelock_;
+        guardian = guardian_;
+        for (uint256 i; i < initialSigners.length; i++) {
+            address s = initialSigners[i];
+            if (s == address(0)) revert ZeroAddress();
+            _signers[s] = true;
+            emit SignerSet(s, true);
+        }
+    }
+
+    // ─── IGovernanceView ──────────────────────────────────────────
+
+    /// @inheritdoc IGovernanceView
+    function isPaused() external view returns (bool) {
+        return _paused;
+    }
+
+    /// @inheritdoc IGovernanceView
+    function isSigner(address who) external view returns (bool) {
+        return _signers[who];
+    }
+
+    // ─── Pause / Unpause ──────────────────────────────────────────
+
+    /// @notice Emergency pause. Callable by the guardian without delay.
+    function pause() external {
+        if (msg.sender != guardian) revert NotGuardian(msg.sender);
+        _paused = true;
+        emit Paused(msg.sender);
+    }
+
+    /// @notice Unpause. Requires the timelock (a deliberate 24h
+    ///         decision); guardian alone cannot unpause.
+    function unpause() external {
+        if (msg.sender != timelock) revert NotTimelock(msg.sender);
+        _paused = false;
+        emit Unpaused(msg.sender);
+    }
+
+    // ─── Slow-path governance (timelock only) ─────────────────────
+
+    /// @notice Forward a call to a `GovernanceManaged` target. The
+    ///         target sees `msg.sender == address(this)`, satisfying
+    ///         its `onlyGovernance` modifier. Only callable by the
+    ///         timelock (every action sees a 24h delay before execute).
+    function execute(address target, bytes calldata data, uint256 value)
+        external
+        payable
+        returns (bytes memory)
+    {
+        if (msg.sender != timelock) revert NotTimelock(msg.sender);
+        (bool ok, bytes memory result) = target.call{value: value}(data);
+        if (!ok) revert ExecuteFailed(target, result);
+        emit Executed(target, value, data);
+        return result;
+    }
+
+    /// @notice Add / remove a signer (consumed by `isSigner` reads from
+    ///         downstream `GovernanceManaged` contracts).
+    function setSigner(address who, bool sig) external {
+        if (msg.sender != timelock) revert NotTimelock(msg.sender);
+        _signers[who] = sig;
+        emit SignerSet(who, sig);
+    }
+
+    // ─── Receive ETH ──────────────────────────────────────────────
+
+    receive() external payable {}
+}

package/src/governance/GovernanceManaged.sol

@@ -0,0 +1,75 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.28;
+
+import "./IGovernance.sol";
+
+/**
+ * @title GovernanceManaged
+ * @notice Base contract that gates admin functions behind a single
+ *         `Governance` multisig + timelock, and exposes a pause hook so
+ *         downstream writes can be killed system-wide in an incident.
+ *
+ *         Spec 007 Phase A.5 (SC4 § 4.2). The `governance` address is
+ *         immutable per deploy — to "upgrade" governance for a contract,
+ *         you redeploy the contract pointing at the new governance.
+ *         Governance itself is non-upgradeable.
+ *
+ *         Inheritors gain:
+ *           - `onlyGovernance` modifier for setters / admin functions.
+ *           - `whenNotPaused` modifier for write-surface functions that
+ *             should freeze during an incident.
+ *           - A pause-aware view (`paused()`) for off-chain tooling.
+ */
+abstract contract GovernanceManaged {
+    /// @notice The Governance multisig + timelock contract that owns
+    ///         admin authority over this contract.
+    address public immutable governance;
+
+    error NotGovernance();
+    error SystemPaused();
+    error ZeroGovernance();
+
+    constructor(address governance_) {
+        if (governance_ == address(0)) revert ZeroGovernance();
+        governance = governance_;
+    }
+
+    /// @dev Only the governance contract (executing a passed proposal)
+    ///      can call functions protected by this modifier.
+    modifier onlyGovernance() {
+        if (msg.sender != governance) revert NotGovernance();
+        _;
+    }
+
+    /// @dev Reverts when the governance pause flag is set. Read-only
+    ///      functions stay live; this is for write-surface protection
+    ///      only.
+    ///
+    ///      H7-C.10: skipped when `governance` is an EOA or a contract
+    ///      that doesn't implement `IGovernanceView` (legacy / test
+    ///      deploys). Production deploys MUST pass an
+    ///      `AgenticGovernance` contract; the production-deploy
+    ///      preflight (`check:production-deploy`) enforces that.
+    modifier whenNotPaused() {
+        if (_pausedSafe()) revert SystemPaused();
+        _;
+    }
+
+    /// @notice Read the global pause flag. Returns false when governance
+    ///         is non-conforming.
+    function paused() external view returns (bool) {
+        return _pausedSafe();
+    }
+
+    /// @dev Calls `governance.isPaused()` via staticcall and treats any
+    ///      failure (EOA, missing function, revert) as "not paused" so
+    ///      legacy / test deploys with a non-conforming governance still
+    ///      work. Production deploys ALWAYS use `AgenticGovernance` which
+    ///      implements `IGovernanceView`.
+    function _pausedSafe() internal view returns (bool) {
+        if (governance.code.length == 0) return false;
+        (bool ok, bytes memory data) = governance.staticcall(abi.encodeWithSelector(IGovernanceView.isPaused.selector));
+        if (!ok || data.length < 32) return false;
+        return abi.decode(data, (bool));
+    }
+}

package/src/governance/IGovernance.sol

@@ -0,0 +1,15 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.28;
+
+/// @title IGovernanceView
+/// @notice Minimal read surface every `GovernanceManaged` contract depends
+///         on. The pause flag flows through here so we can short-circuit
+///         writes without pulling in the whole governance type.
+interface IGovernanceView {
+    /// @notice Global system-pause flag.
+    function isPaused() external view returns (bool);
+
+    /// @notice Whether `who` is currently authorised to call `emergencyPause`
+    ///         on behalf of governance (i.e. they're an active signer).
+    function isSigner(address who) external view returns (bool);
+}

package/src/identity/AgentProfilePredicates.sol

@@ -0,0 +1,40 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.28;
+
+/**
+ * @title AgentProfilePredicates
+ * @notice Canonical bytes32 ids for identity-profile predicates,
+ *         registered in the shared OntologyTermRegistry alongside
+ *         the AgentName predicates from NS Phase 3.
+ *
+ * Some predicates are SHARED with AgentName (`atl:displayName`,
+ * `atl:metadataURI`, `atl:metadataHash`, `atl:agentKind`) — same
+ * vocabulary across stores is the whole point of the central
+ * OntologyTermRegistry. The IDs here that overlap MUST equal the
+ * AgentName ones (they're both `keccak256("atl:displayName")` etc.).
+ *
+ * Identity-only predicates (`atl:description`, `atl:homepage`,
+ * `atl:avatar`, `atl:profileSchemaURI`, `atl:profileActive`,
+ * `atl:profileRegisteredAt`) are NEW and registered by Deploy.s.sol.
+ */
+library AgentProfilePredicates {
+    // ─── Shared with AgentName (MUST equal AgentNamePredicates.*) ────
+
+    bytes32 internal constant ATL_DISPLAY_NAME      = keccak256("atl:displayName");
+    bytes32 internal constant ATL_AGENT_KIND        = keccak256("atl:agentKind");
+    bytes32 internal constant ATL_METADATA_URI      = keccak256("atl:metadataURI");
+    bytes32 internal constant ATL_METADATA_HASH     = keccak256("atl:metadataHash");
+
+    // ─── Identity-only ──────────────────────────────────────────────
+
+    bytes32 internal constant ATL_DESCRIPTION       = keccak256("atl:description");
+    bytes32 internal constant ATL_HOMEPAGE          = keccak256("atl:homepage");
+    bytes32 internal constant ATL_AVATAR            = keccak256("atl:avatar");
+    bytes32 internal constant ATL_PROFILE_SCHEMA_URI = keccak256("atl:profileSchemaURI");
+    bytes32 internal constant ATL_PROFILE_ACTIVE    = keccak256("atl:profileActive");
+    bytes32 internal constant ATL_PROFILE_REGISTERED_AT = keccak256("atl:profileRegisteredAt");
+
+    // ─── Class id ───────────────────────────────────────────────────
+
+    bytes32 internal constant CLASS_AGENT_PROFILE   = keccak256("atl:AgentProfile");
+}

package/src/identity/AgentProfileResolver.sol

@@ -0,0 +1,194 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.28;
+
+import "../ontology/AttributeStorage.sol";
+import "./AgentProfilePredicates.sol";
+
+/**
+ * @title AgentProfileResolver
+ * @notice Per-agent profile resolver. Inherits the shared
+ *         AttributeStorage so writes are predicate-active-checked
+ *         against the OntologyTermRegistry deployed in NS Phase 3.
+ *
+ * Subject encoding: `bytes32(uint256(uint160(agent)))`. This places
+ * the agent's address in the low 20 bytes of the bytes32 subject id
+ * — same convention smart-agent uses, lets the SDK convert
+ * mechanically between `address` and `subject` without lookup.
+ *
+ * Authorization: `msg.sender == agent`. The agent's Smart Agent
+ * executes through its CustodyPolicy gate, then calls into this
+ * contract — `msg.sender` here equals the agent. No isOwner fallback
+ * (our AgentAccount has no built-in owner registry; quorum belongs
+ * in the CustodyPolicy module).
+ *
+ * Adapted from smart-agent
+ * (`packages/contracts/src/AgentAccountResolver.sol`, 274 LOC) with
+ * the following simplifications per spec 217 § Phase 3 + ADR-0007:
+ *
+ *   - Single auth path (`msg.sender == agent`) — no isOwner staticcall.
+ *   - Profile shape (`atl:AgentProfile`) defined in ShapeRegistry,
+ *     not via a hand-written `CoreRecord` struct here.
+ *   - Off-chain `AgentCard` JSON is the source of truth; this
+ *     resolver stores the content-hash anchor + typed metadata only.
+ */
+contract AgentProfileResolver is AttributeStorage {
+    address[] private _agents;
+    mapping(address => bool) private _registered;
+
+    event AgentRegistered(address indexed agent, string displayName, bytes32 indexed agentKind);
+    event MetadataUpdated(address indexed agent, string metadataURI, bytes32 metadataHash);
+    event PropertySet(address indexed agent, bytes32 indexed predicate);
+
+    error NotAgentOwner();
+    error AlreadyRegistered();
+    error NotRegistered();
+
+    /// @notice `msg.sender == agent` (the canonical path). For any
+    ///         other principal, callers must route through their own
+    ///         CustodyPolicy / AgentAccount execute path.
+    modifier onlyAgent(address agent) {
+        if (msg.sender != agent) revert NotAgentOwner();
+        _;
+    }
+
+    modifier onlyRegistered(address agent) {
+        if (!_registered[agent]) revert NotRegistered();
+        _;
+    }
+
+    constructor(address ontologyRegistry) AttributeStorage(ontologyRegistry) {}
+
+    function _subject(address agent) internal pure returns (bytes32) {
+        return bytes32(uint256(uint160(agent)));
+    }
+
+    // ─── Registration ───────────────────────────────────────────────
+
+    /**
+     * @notice One-time profile registration for a Smart Agent. The
+     *         agent calls this on itself (`msg.sender == agent`).
+     *         Subsequent edits go through the typed setters below.
+     */
+    function register(
+        address agent,
+        string calldata displayName,
+        string calldata description,
+        bytes32 agentKind,
+        string calldata profileSchemaURI
+    ) external onlyAgent(agent) {
+        if (_registered[agent]) revert AlreadyRegistered();
+        bytes32 s = _subject(agent);
+        _setString(s, AgentProfilePredicates.ATL_DISPLAY_NAME, displayName);
+        if (bytes(description).length > 0) {
+            _setString(s, AgentProfilePredicates.ATL_DESCRIPTION, description);
+        }
+        if (agentKind != bytes32(0)) {
+            _setBytes32(s, AgentProfilePredicates.ATL_AGENT_KIND, agentKind);
+        }
+        if (bytes(profileSchemaURI).length > 0) {
+            _setString(s, AgentProfilePredicates.ATL_PROFILE_SCHEMA_URI, profileSchemaURI);
+        }
+        _setBool(s, AgentProfilePredicates.ATL_PROFILE_ACTIVE, true);
+        _setUint(s, AgentProfilePredicates.ATL_PROFILE_REGISTERED_AT, block.timestamp);
+        _registered[agent] = true;
+        _agents.push(agent);
+        emit AgentRegistered(agent, displayName, agentKind);
+    }
+
+    // ─── Typed setters ──────────────────────────────────────────────
+
+    function setMetadata(
+        address agent,
+        string calldata metadataURI,
+        bytes32 metadataHash
+    ) external onlyAgent(agent) onlyRegistered(agent) {
+        bytes32 s = _subject(agent);
+        _setString(s, AgentProfilePredicates.ATL_METADATA_URI, metadataURI);
+        _setBytes32(s, AgentProfilePredicates.ATL_METADATA_HASH, metadataHash);
+        emit MetadataUpdated(agent, metadataURI, metadataHash);
+    }
+
+    function setStringProperty(address agent, bytes32 predicate, string calldata value)
+        external onlyAgent(agent) onlyRegistered(agent)
+    {
+        _setString(_subject(agent), predicate, value);
+        emit PropertySet(agent, predicate);
+    }
+
+    function setAddressProperty(address agent, bytes32 predicate, address value)
+        external onlyAgent(agent) onlyRegistered(agent)
+    {
+        _setAddress(_subject(agent), predicate, value);
+        emit PropertySet(agent, predicate);
+    }
+
+    function setBoolProperty(address agent, bytes32 predicate, bool value)
+        external onlyAgent(agent) onlyRegistered(agent)
+    {
+        _setBool(_subject(agent), predicate, value);
+        emit PropertySet(agent, predicate);
+    }
+
+    function setBytes32Property(address agent, bytes32 predicate, bytes32 value)
+        external onlyAgent(agent) onlyRegistered(agent)
+    {
+        _setBytes32(_subject(agent), predicate, value);
+        emit PropertySet(agent, predicate);
+    }
+
+    function setUintProperty(address agent, bytes32 predicate, uint256 value)
+        external onlyAgent(agent) onlyRegistered(agent)
+    {
+        _setUint(_subject(agent), predicate, value);
+        emit PropertySet(agent, predicate);
+    }
+
+    function setActive(address agent, bool active)
+        external onlyAgent(agent) onlyRegistered(agent)
+    {
+        _setBool(_subject(agent), AgentProfilePredicates.ATL_PROFILE_ACTIVE, active);
+        emit PropertySet(agent, AgentProfilePredicates.ATL_PROFILE_ACTIVE);
+    }
+
+    // ─── Convenience readers ────────────────────────────────────────
+
+    function isRegistered(address agent) external view returns (bool) {
+        return _registered[agent];
+    }
+
+    function getStringProperty(address agent, bytes32 predicate) external view returns (string memory) {
+        return this.getString(_subject(agent), predicate);
+    }
+
+    function getAddressProperty(address agent, bytes32 predicate) external view returns (address) {
+        return this.getAddress(_subject(agent), predicate);
+    }
+
+    function getBoolProperty(address agent, bytes32 predicate) external view returns (bool) {
+        return this.getBool(_subject(agent), predicate);
+    }
+
+    function getBytes32Property(address agent, bytes32 predicate) external view returns (bytes32) {
+        return this.getBytes32(_subject(agent), predicate);
+    }
+
+    function getUintProperty(address agent, bytes32 predicate) external view returns (uint256) {
+        return this.getUint(_subject(agent), predicate);
+    }
+
+    function getPredicateKeys(address agent) external view returns (bytes32[] memory) {
+        return this.predicatesOf(_subject(agent));
+    }
+
+    function agentCount() external view returns (uint256) {
+        return _agents.length;
+    }
+
+    function getAllAgents() external view returns (address[] memory) {
+        return _agents;
+    }
+
+    function subjectFor(address agent) external pure returns (bytes32) {
+        return bytes32(uint256(uint160(agent)));
+    }
+}

package/src/libraries/MultiSendCallOnly.sol

@@ -0,0 +1,95 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.28;
+
+/**
+ * @title MultiSendCallOnly
+ * @notice Atomic batched-call library, ported from Safe's
+ *         `MultiSendCallOnly` shape. Lets an `AgentAccount` execute
+ *         multiple inner calls in one userOp without changing
+ *         `execute`'s ABI — important for flows like
+ *         `approveHash + redeem` (multi-sig pre-approval path) and the
+ *         coming Treasury withdraw + emit-event combinations.
+ *
+ * @dev This is the **call-only** variant. The full Safe `MultiSend`
+ *      supports `op = 1` (delegatecall) but we explicitly disallow it
+ *      here because delegatecall from a smart account whose authority
+ *      is gated by caveats is a footgun — a single malicious target
+ *      can nullify every caveat we enforce. If you need
+ *      delegatecall semantics inside a quorum-gated flow, build a
+ *      dedicated module + caveat rather than reaching for this
+ *      library.
+ *
+ *      Packed format per entry (one slot):
+ *        {1 byte op}{20 bytes target}{32 bytes value}{32 bytes dataLen}{dataLen bytes data}
+ *      where `op` MUST be 0 (call). Total slot size is `0x55 + dataLen`.
+ *
+ *      MUST be invoked via `delegatecall` from the caller's
+ *      `AgentAccount` so each inner call's `msg.sender` is the account
+ *      itself (not this library). This contract is stateless — safe
+ *      to deploy once per chain and reuse from any account.
+ *
+ *      Reverts on the first inner failure with the failing call index
+ *      and the inner revert data so callers can decode which sub-call
+ *      broke.
+ */
+library MultiSendCallOnly {
+    error InvalidOperation(uint8 op);
+    error CallFailed(uint256 index, bytes returnData);
+
+    /**
+     * @notice Iterate the packed batch and invoke each call.
+     */
+    function multiSend(bytes memory transactions) internal {
+        uint256 i;
+        uint256 n = transactions.length;
+        uint256 callIndex;
+        while (i < n) {
+            uint8 operation;
+            address to;
+            uint256 value;
+            uint256 dataLength;
+            bytes memory data;
+
+            assembly {
+                let pos := add(transactions, add(0x20, i))
+                operation := shr(248, mload(pos))            // 1 byte
+                to := shr(96, mload(add(pos, 0x01)))          // 20 bytes
+                value := mload(add(pos, 0x15))                // 32 bytes
+                dataLength := mload(add(pos, 0x35))           // 32 bytes
+            }
+
+            if (operation != 0) revert InvalidOperation(operation);
+
+            // Slice the data segment into a fresh `bytes`.
+            data = new bytes(dataLength);
+            assembly {
+                let pos := add(transactions, add(0x20, i))
+                let dataStart := add(pos, 0x55)
+                let dst := add(data, 0x20)
+                for { let j := 0 } lt(j, dataLength) { j := add(j, 0x20) } {
+                    mstore(add(dst, j), mload(add(dataStart, j)))
+                }
+            }
+
+            (bool success, bytes memory ret) = to.call{ value: value }(data);
+            if (!success) revert CallFailed(callIndex, ret);
+
+            // Advance: 1 + 20 + 32 + 32 + dataLength
+            i += 0x55 + dataLength;
+            callIndex += 1;
+        }
+    }
+}
+
+/**
+ * @title MultiSendCallOnlyHarness
+ * @notice Test-only wrapper that exposes `multiSend` as an external
+ *         entry point so Foundry can invoke it directly. Production
+ *         usage `delegatecall`s the library from an `AgentAccount`.
+ */
+contract MultiSendCallOnlyHarness {
+    function multiSend(bytes calldata transactions) external payable {
+        bytes memory copy = transactions;
+        MultiSendCallOnly.multiSend(copy);
+    }
+}