Proposals

The Proposals panel (/proposals) surfaces structured action suggestions that agents emit during a conversation. Instead of executing high-impact actions silently, an agent can emit a proposal that is either auto-approved based on confidence or held for human review.

What are Proposals?

When an agent determines that an action — creating an issue, spawning a sub-agent, triggering a pipeline, modifying a schedule — would benefit from human oversight, it emits a <proposal> block in its response. Nexora strips that block from the visible chat output and processes it separately.

Each proposal carries:

Field	Description
Type	The kind of action proposed (see Proposal Types)
Title	A short human-readable description
Rationale	The agent’s reasoning for why this action is appropriate
Confidence	A score between 0 and 1 indicating how certain the agent is
Payload	The action-specific parameters (issue title, agent config, etc.)

How Proposals Work

The agent includes a <proposal> JSON block in its response as it streams.
Nexora’s proposal_parser service extracts and persists the proposal.
If the confidence score meets or exceeds the auto-approval threshold, the action is executed immediately and the proposal is marked auto_approved.
If the confidence is below the threshold, the proposal is saved as pending and a real-time notification is broadcast to the UI so you can review it.

Set PROPOSAL_AUTO_APPROVE_CONFIDENCE in your .env to control the auto-approval threshold. The default is 0.85. Agents that are confident enough proceed without interrupting you; lower-confidence proposals wait for your approval.

Proposal Types

Type	What it does when approved
`create_issue`	Creates a project issue via the issue management tool
`create_task`	Creates a task on the task board
`spawn_agent`	Instantiates a new agent on the platform
`trigger_pipeline`	Triggers a GitLab pipeline via the GitLab integration
`modify_schedule`	Proposes a change to a schedule (queued for manual execution)
`custom`	Any agent-defined action (queued for manual execution)

Only the four executable types (create_issue, create_task, spawn_agent, trigger_pipeline) run automatically when approved. Any other proposal_type — including modify_schedule and custom — is approved in status but not automatically executed; the execution result notes that manual handling is needed.

Proposal Statuses

Status	Meaning
`pending`	Waiting for human review
`approved`	Manually approved and executed
`rejected`	Manually rejected; the action was not taken
`auto_approved`	Confidence threshold met; automatically executed without human review

Reviewing a Proposal

When an agent emits a pending proposal, a notification appears in the chat interface. To review all proposals for your organization:

Navigate to Proposals in the sidebar (/proposals).
The panel lists proposals across all chats, most recent first. Use the status filter to show only pending proposals.
Click a proposal to expand the rationale and payload.
Click Approve to execute the action immediately. The execution_result is recorded on the proposal.
Click Reject to dismiss the proposal. No action is taken.

Both actions require the proposal to currently be in pending status — attempting to re-review an already-actioned proposal returns a 400 error.

Approving a proposal executes the underlying action immediately (creates the issue, spawns the agent, triggers the pipeline, etc.). Review the rationale and payload before approving.

Auto-Approval

High-confidence proposals bypass the review queue entirely. The flow:

Agent emits a proposal with "confidence": 0.92 (above the 0.85 default).
proposal_parser persists the proposal, executes the action, and sets status = "auto_approved".
The result is stored on the proposal for audit purposes.
The proposal still appears in the Proposals panel under the auto_approved filter so you can audit what was done automatically.

To require all proposals to go through human review, set PROPOSAL_AUTO_APPROVE_CONFIDENCE=1.0 in your .env. To auto-approve everything, set it to 0.0.

API Reference

Proposals are managed via the /api/proposals endpoints:

Method	Endpoint	Description
`GET`	`/api/proposals`	List proposals for the active org. Accepts `?status=pending,approved,rejected,auto_approved` (comma-separated)
`POST`	`/api/proposals/{id}/approve`	Approve and execute a pending proposal
`POST`	`/api/proposals/{id}/reject`	Reject a pending proposal

See the API Reference for authentication details.