DE EN
Visual for Agent Awareness Gates Orientation and Safety Agent Awareness Gates AAG is Nova's top-level gate system for agent awareness: it warns or stops agents when important prerequisites, page perception, user control, or safety conditions are missing. Overview Gates When it matters Workflow Warning/block rules Agent Tools

Agent Awareness Gates

AAG stands for Agent Awareness Gates. These gates make agents aware of missing prerequisites, uncertain page state, and safety boundaries before they continue.

AAG is Nova’s top-level layer for agent orientation and stop conditions. It checks the step between an agent’s intent and a tool call that would affect a browser, task, file, resource, or account-sensitive surface.

A gate can warn, block, or return structured recovery guidance. It keeps an agent from acting as if it knows something that has not been checked yet.

AAG keeps safety concrete: the agent loads the right tools, perceives the page, respects user control, and stops when the environment is not safe. Learning can use the signals, and TOB can record blocked preflight steps as evidence.

In short

  • AAG is Nova’s top-level awareness and safety gate layer for agent tool use.
  • It can warn or block when setup, page perception, user control, or resource safety is missing.
  • It gives agents structured recovery hints instead of letting them guess.
  • It is relevant to learning, TOB, ETM, automation, screenshots, and browser interaction.
  • A block is not a failed run; Nova simply does not execute the call until the missing condition is fixed.

What AAG checks

AAG groups several kinds of gates. They all ask whether the agent has enough verified context to proceed.

  1. Setup readiness Before active browsing, an agent should know the tool contract and load the right capability bundle, for example through nova.get_instructions and nova.tools_bundle.
  2. Page perception After navigation or a target change, AAG can require a fresh nova.perceive before the agent clicks, types, submits, or trusts stale page assumptions.
  3. User control When a user stops a run or a visible approval is required, AAG keeps the agent from continuing as if permission still existed.
  4. Resource safety Some gates protect the execution environment, such as low disk space or screenshot captures that would be too large or too expensive to return inline.
  5. Task and tab awareness AAG can remind an agent that work should stay in the intended tab, task instance, or workspace instead of drifting into unrelated browser state.

When this matters

AAG applies whenever Nova gives an agent real tools. It is especially relevant for login-sensitive pages, form input, multi-step automations, screenshots, scheduled work, long task runs, and any flow where a stale assumption could cause the agent to click, type, upload, or finish too early.

Important terms

These terms help distinguish guidance, blocks, and recovery.

Gate
A check that evaluates whether an agent may continue with the requested action.
Warning
A signal that work can still return a result, but the agent should fix orientation before continuing.
Block
A stop condition where the requested tool call is not executed until the missing prerequisite is resolved.
Clear condition
The action that satisfies the gate, such as loading a bundle, perceiving the page, freeing storage, or waiting for user release.
Retry
A deliberate repeat of the original call after the gate condition has been fixed. It is not permission to keep trying blindly.
Preflight
A check that happens before a tool action mutates the page or environment.

How it works

AAG checks the next tool call before it changes the page or environment.

  1. The agent intends to act An agent asks Nova to use a tool, such as reading a page, clicking an element, capturing a screenshot, or continuing a task.
  2. Nova checks context AAG checks whether the relevant prerequisite is present: bundle loaded, page perceived, user control intact, resource safe, and context clear.
  3. The gate responds If the condition is satisfied, the tool continues. If not, AAG returns a warning or a structured block with the gate identity and next recovery step.
  4. The agent resolves the issue The agent may load nova.tools_bundle, call nova.perceive, wait for user release, reduce screenshot size, or report that the run cannot continue safely.
  5. Work resumes deliberately Only after the condition is fixed should the agent retry the original action or choose a safer alternative.

Limits and safety

AAG does not replace user approval, account rules, credential handling, or destructive-action policy. It also does not make a blocked action safe by itself. A gate tells the agent what is missing; the current page, task, user intent, and safety settings still decide what may happen next.

Example

An agent navigates to a login page and immediately tries to type. AAG can require nova.perceive first, because the visible page may be different from the agent’s expectation. If a login wall, identity overlay, or wrong field is visible, the agent has a chance to stop and ask instead of typing into the wrong element.

Warning and block rules

These values describe Nova’s documented defaults for agent gates. They are signals for agents, not controls for normal users.

Gate Observed Default / threshold Behavior
setup.bootstrap_required Whether the agent loaded an appropriate tool bundle before active work. First non-exempt work call without a successful bundle. Blocks by default and returns the suggested recovery bundle.
safety.perceive_first Whether the visible page or target has fresh perception after navigation or target changes. Mutating interaction without current perception on the same target. Blocks until the agent perceives the page.
safety.disk_space_low Free storage on the relevant Nova or agent working location. 500 MB or less free space; clears above 500 MB. Blocks without force bypass; retry is useful only after freeing storage.
safety.emergency_stop Whether user control has stopped or locked agent work. Manual stop or active stop lock. Blocks new tool work until the user releases the stop condition.
aag.screenshot_budget Inline screenshot size, source pixels, and capture budget. Warns above 200 KB; overridable limits apply above 1 MB, above 16 MP, or at 10,000 px on one side; absolute limits apply above 50 MB or 50 MP. Warns, downgrades the response, or blocks; absolute safety limits cannot be overridden.
etm.task_discovery_recommended Whether task-aware work starts without checking matching ETM task profiles. First work call when task profiles exist but no task discovery happened. Warns only and clears after task search, match, create, or instance lookup.
etm.active_instance_context Whether active ETM task instances are being ignored during ongoing work. Normally after 12 work calls without task-instance interaction; stale instances are ignored. Warns as a reminder so the agent keeps the active task context in view.
safety.tab_awareness Whether the agent uses the active tab while its tab awareness is stale. Active-tab state changed after the agent last refreshed tab context. Warns; refreshing tab context or using an explicit target removes the ambiguity.
pks.semantic_learning Whether a repeated same-origin situation should become a learning candidate. Warns after repeated eligible calls without resolving the learning prompt. Warns in the normal mode; stricter deployments may turn part of the flow into a block.
pks.spa_navigation_block Whether hard navigation would lose a fragile single-page app or login state known from PKS. Known navigation risk on the current route without an explicit override. Blocks or warns according to policy; an explicit override may bypass the route block.
claim.reclaim_notification Whether another agent has reclaimed a tab and left a handover message. Next affected work call after the reclaim event. Blocks once to deliver the message, then the notification is consumed.
Agent Tools

MCP tools for agents. These variables and tool names are intended for agents and integrators. They are not normal user controls in the interface.

Variable Meaning
nova.get_instructions Read Learn Mode instructions
nova.tools_bundle Load tool bundles
nova.perceive Understand the visible page
nova.tab_claim Reserve a tab for work
nova.tab_release Release a reserved tab
nova.capture_screenshot Capture a screenshot
nova.permission_prompt Ask for user permission
bootstrapWarning Structured warning that the agent should load the right tool bundle before continuing.
bootstrapWarning.message Human-readable setup note that also appears when self-onboarding guidance is triggered.
bootstrapWarning.loadedBundles Bundles already loaded in the current MCP session.
bootstrapWarning.resolution Structured next step for clearing the bootstrap warning.
_meta["io.nova/aag"] Model Context Protocol metadata area used when AAG returns a structured block.
_meta["io.nova/onboarding"] Machine-readable self-onboarding advisory for setup guidance, emitted once per MCP session.
gateId Stable identifier for the gate that warned or blocked the call.
gateMode Indicates whether the gate is warning, advisory, or blocking for this call.
status Compact result state such as passed, warned, blocked, timeout, or ok.
stage Pipeline stage where the warning or block was produced.
retryable Indicates whether the original call may be retried after the missing condition is fixed.
retryAfterMs Suggested wait time before retrying a transient gate or activation timeout.
reasonCode Machine-readable reason for the warning or block.
details Structured gate details, such as recovery options, limits, or non-bypassable safety state.
targetId Canonical browser target identifier for target-scoped gate checks.
pageUrl Sanitized page URL known to the tool response.
pageTitle Sanitized visible page title known to the tool response.
pageState Compact page condition such as ok, login_required, consent_required, bot_challenge, or geo_blocked.
knownBundles Tool bundles known to Nova, so agents can choose the right capability group.
preferredBundle Suggested bundle for the current recovery path.
forceBypassAvailable Signals whether a force-style bypass is possible; some safety gates deliberately have none.
autofillWarning Form-analysis signal that password manager or autofill state may be invisible to MCP tools.
autofillPopupWarning Signal from click or typing tools that an autofill popup may have appeared outside MCP visibility.
autofillFieldRole Optional role hint such as login_identifier or password for autofill-sensitive fields.
identityOverlayWarning Awareness object for visible identity, SSO, payment, or consent overlays.
identityOverlayWarning.items[] Detected overlay items with provider, origin, confidence, blocking state, and evidence.
identityOverlayWarning.recommendedAction Agent-facing action such as asking the user before continuing or requiring approval.
truncationWarning Readback signal that typed text was stored shorter than requested.
nativeDialogWarning Signal that a native browser dialog may require user handling outside MCP visibility.
fileInputRisk Risk level for a click path that may open a file chooser.
fileInputRiskReason Short explanation for the file-input risk classification.
fileUploadSelectorHint Suggested selector path for safer file upload handling.
fileChooserBackendNodeId Backend node identifier exposed when Nova intercepts a file chooser.
frameworkHints[] Advisory hints for controlled form frameworks and safe interaction style.
responseMode Screenshot response mode: inline, reference, thumbnail+reference, or auto.
screenshotFilePath Local saved screenshot path exposed when a tool stores a capture on disk.
snapshot.snapshotId Identifier for a persisted overflow snapshot that can be queried later.
snapshot.queryTool Follow-up tool to read, search, outline, or chunk a persisted snapshot.
_aagGates Structured collection of advisory gate states included in rich tool responses.
taskUrlCoverage Task URL coverage state used when ETM prevents premature completion.
forceCompleteEnabled Signals whether a task-completion gate allows an explicit user-forced finish path.
authPersistenceCached Navigation signal that Nova has remembered authentication or session persistence risk.
pksNavigationWarning PKS-derived warning that navigation could lose fragile page or login state.
setup.bootstrap_required Gate that asks an agent to load an appropriate tool bundle before active work.
safety.perceive_first Gate that requires fresh page perception before risky or mutating interaction.
safety.identity_overlay Gate identity for detected identity, SSO, payment, or account-sensitive overlays.
safety.emergency_stop Gate used when user control has stopped agent tool work.
safety.disk_space_low Gate that stops work when local storage is too low for safe execution.
aag.screenshot_budget Gate that keeps screenshot capture within safe size and token-budget boundaries.
domain.policy.blocked Policy reason when the current domain or action group is blocked.
agent.new_tabs_disabled Policy reason when an agent is not allowed to open new tabs.
agent.cross_tab_navigation_disabled Policy reason when an agent is not allowed to move work across tabs.
loop.detected Gate reason for repeated tool loops that need user or agent correction.
proxy.credentials.bundle_required Gate reason when proxy credential handling requires the proper bundle and setup context.

Related topics

AAG sits across agent work, evidence, learning, and automation:

Agent Sidecars TOB Learning Automation