Summary by CodeRabbit

• New Features

  • Approval workflow gates: sensitive actions can escalate, park agents, and resume after human decisions
  • Agent-callable human-approval tool to request and track approvals
  • Frontend WebSocket handling updated to reconcile approvals by approval_id and re-fetch as needed

• Documentation

  • README and design docs updated to describe approval gates and approval-resume scheduler

• Observability

  • Event-driven logging extended with approval-gate events (park/resume/escalation)

• Validation / API

  • Stronger validation for action_type and TTLs; improved approval request handling and responses

Walkthrough

Adds a human-approval workflow: new ApprovalGate service and models, a request_human_approval tool, ToolInvoker escalation tracking, engine loop wiring to park/resume contexts, API/DTO/controller changes for approvals, observability event constants, DB migration for parked_context.task_id, and frontend WS handling updates.

Changes

Sequence Diagram(s)

sequenceDiagram
    participant Agent as Agent (Execution Loop)
    participant Invoker as ToolInvoker
    participant Gate as ApprovalGate
    participant Park as ParkService
    participant Repo as ParkedContextRepo
    participant API as Approvals API
    participant Store as ApprovalStore

    Agent->>Invoker: invoke tool call(s)
    Invoker->>Invoker: execute tools & collect verdicts
    alt escalation detected
        Invoker-->>Agent: pending_escalations (EscalationInfo)
        Agent->>Gate: should_park(escalations)?
        Gate-->>Agent: escalation to park (EscalationInfo)
        Agent->>Gate: park_context(escalation, context)
        Gate->>Park: serialize(context)
        Park-->>Gate: ParkedContext
        Gate->>Repo: persist parked context (optional)
        Repo-->>Gate: persisted
        Gate-->>Agent: parked (approval_id)
        Agent-->>Agent: return PARKED ExecutionResult
    end

    rect rgba(50,150,200,0.5)
        API->>Store: create/list/decide ApprovalItem
        Store-->>API: decision saved
        API->>Gate: resume_context(approval_id)
        Gate->>Repo: load_by_approval_id
        Repo-->>Gate: ParkedContext
        Gate->>Park: deserialize -> AgentContext
        Park-->>Gate: AgentContext
        Gate->>Repo: cleanup(delete)
        Repo-->>Gate: deleted
        Gate-->>API: AgentContext
        API-->>Agent: inject resume message / continue execution
    end

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Possibly related issues

• feat: implement approval workflow gates in engine #258 (feat: implement approval workflow gates in engine): This PR implements engine-level approval gates, escalation detection, context parking/resumption, and resume integration that match the issue objectives.

Possibly related PRs

• feat: add autonomy levels and approval timeout policies (#42, #126) #197: Overlapping changes to park/resume plumbing, parked-context persistence, and observability events.
• feat: centralized single-writer TaskEngine with full CRUD API #328: Similar AppState constructor/DI changes and engine export surface adjustments (approval_gate injection).
• feat: incremental AgentEngine → TaskEngine status sync #331: Related AgentEngine/loop handling of PARKED outcomes and resume handling that may intersect with this approval-gate integration.

❌ Failed checks (1 warning)

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

• 📝 Generate docstrings (stacked PR)
• 📝 Generate docstrings (commit on current branch)

• Generate coding plan for human review comments

• CLAUDE.md
  • Updated descriptions for api/, engine/, and tools/ directories to reflect approval gate integration.
• README.md
  • Updated project status to indicate that approval workflow gates are now implemented.
• docs/design/engine.md
  • Added a new section detailing how the ApprovalGate evaluates escalations and parks the agent context within the execution loop.
• src/ai_company/api/approval_store.py
  • Added save_if_pending method for optimistic concurrency control when updating approval items.
  • Improved error handling for the _on_expire callback to log exceptions without preventing expiration.
• src/ai_company/api/controllers/approvals.py
  • Imported new event constants API_AUTH_FAILED and APPROVAL_GATE_RESUME_TRIGGERED.
  • Refactored _resolve_decision to prioritize status check before user authentication.
  • Added _log_approval_decision and _signal_resume_intent helper functions for logging and future scheduler integration.
  • Enforced requested_by field to be populated from the authenticated user's username during approval creation.
  • Switched approve and reject endpoints to use save_if_pending for atomic updates and added ConflictError handling.
  • Integrated _log_approval_decision and _signal_resume_intent into approve and reject flows.
• src/ai_company/api/dto.py
  • Imported field_validator for Pydantic model validation.
  • Imported is_valid_action_type for shared validation.
  • Removed requested_by from CreateApprovalRequest as it's now populated by the authenticated user.
  • Added action_type format validation to CreateApprovalRequest using is_valid_action_type.
  • Added ttl_seconds bounds (min 60, max 604800) to CreateApprovalRequest.
  • Added max_length constraint (4096) to ApproveRequest.comment field.
• src/ai_company/api/state.py
  • Imported ApprovalGate.
  • Added _approval_gate to __slots__ for state management.
  • Included approval_gate as an optional parameter in AppState.__init__.
  • Added approval_gate property to AppState.
• src/ai_company/core/validation.py
  • Added new file containing is_valid_action_type function for validating category:action string format.
• src/ai_company/engine/init.py
  • Exported ApprovalGate, EscalationInfo, and ResumePayload from the engine package.
• src/ai_company/engine/_security_factory.py
  • Added new file to encapsulate security interceptor and approval tool registry creation logic, reducing complexity in agent_engine.py.
• src/ai_company/engine/agent_engine.py
  • Imported make_security_interceptor and registry_with_approval_tool from _security_factory.py.
  • Imported ApprovalGate and ParkedContextRepository.
  • Removed direct security interceptor creation logic, delegating to _security_factory.py.
  • Added _approval_store, _parked_context_repo, and _approval_gate attributes.
  • Implemented _make_approval_gate to instantiate ApprovalGate if an approval store is configured.
  • Implemented _make_default_loop to wire the ReactLoop with the ApprovalGate.
  • Updated _make_security_interceptor to use the new factory function.
  • Modified _make_tool_invoker to use registry_with_approval_tool to dynamically add the RequestHumanApprovalTool.
• src/ai_company/engine/approval_gate.py
  • Added new file defining the ApprovalGate class, responsible for managing the parking and resumption of agent contexts based on approval requirements.
  • Includes methods for should_park, park_context, resume_context, and build_resume_message.
• src/ai_company/engine/approval_gate_models.py
  • Added new file defining EscalationInfo and ResumePayload Pydantic models for structured data transfer related to approval events.
• src/ai_company/engine/loop_helpers.py
  • Imported APPROVAL_GATE_PARK_TASKLESS event constant.
  • Added approval_gate parameter to execute_tool_calls function.
  • Implemented logic within execute_tool_calls to check for escalations and call _park_for_approval if parking is required.
  • Added _park_for_approval function to handle the serialization and persistence of agent context when an approval is needed.
• src/ai_company/engine/plan_execute_loop.py
  • Added approval_gate as an optional parameter to PlanExecuteLoop.__init__.
  • Passed self._approval_gate to _handle_step_tool_calls.
• src/ai_company/engine/react_loop.py
  • Added approval_gate as an optional parameter to ReactLoop.__init__.
  • Passed self._approval_gate to _process_turn_response.
• src/ai_company/observability/events/approval_gate.py
  • Added new file defining 16 constants for various approval gate lifecycle events.
• src/ai_company/persistence/sqlite/migrations.py
  • Updated SCHEMA_VERSION to 7.
  • Modified the parked_contexts table schema to make task_id nullable.
  • Added _V7_STATEMENTS for the migration, including creating a new table, copying data, renaming, and dropping the old table.
• src/ai_company/security/timeout/park_service.py
  • Updated the park method to allow task_id to be None, accommodating taskless agents.
• src/ai_company/security/timeout/parked_context.py
  • Modified the ParkedContext model to make the task_id field nullable.
• src/ai_company/tools/init.py
  • Exported RequestHumanApprovalTool from the tools package.
• src/ai_company/tools/approval_tool.py
  • Added new file defining the RequestHumanApprovalTool class, which allows agents to request human approval and signals the engine to park execution.
• src/ai_company/tools/invoker.py
  • Imported ApprovalRiskLevel and EscalationInfo.
  • Added _pending_escalations property to track escalations.
  • Updated _check_security to populate _pending_escalations when an ESCALATE verdict with an approval_id is received.
  • Refactored invoke to use a new _invoke_single method, ensuring _pending_escalations is cleared at the start of each top-level invocation.
  • Added _track_parking_metadata to detect and record tool-initiated parking requests (e.g., from RequestHumanApprovalTool).
  • Implemented sorting for _pending_escalations in invoke_all to ensure deterministic ordering.
• src/ai_company/tools/registry.py
  • Added all_tools method to return all registered tool instances.
• tests/unit/api/controllers/test_approvals.py
  • Updated _create_payload to use the new category:action format for action_type and removed requested_by.
• tests/unit/api/controllers/test_approvals_helpers.py
  • Added new test file for helper functions in the approvals controller, covering _resolve_decision, _log_approval_decision, _signal_resume_intent, and _publish_approval_event.
• tests/unit/api/test_approval_store.py
  • Added tests for the save_if_pending method, covering success, already decided, not found, and expired scenarios.
  • Added tests for combined filters in list_items.
  • Added tests for the on_expire callback, including receiving expired items and handling exceptions.
• tests/unit/api/test_dto.py
  • Added tests for CreateApprovalRequest action type format validation.
  • Added tests for CreateApprovalRequest ttl_seconds bounds validation.
  • Added tests for ApproveRequest comment max_length validation.
• tests/unit/core/test_validation.py
  • Added new test file for is_valid_action_type utility function, covering valid and invalid formats.
• tests/unit/engine/test_approval_gate.py
  • Added new test file for the ApprovalGate service, covering should_park, park_context, resume_context, build_resume_message, and initialization scenarios.
• tests/unit/engine/test_approval_gate_models.py
  • Added new test file for EscalationInfo and ResumePayload models, covering construction, immutability, and validation.
• tests/unit/engine/test_loop_helpers_approval.py
  • Added new test file for approval gate integration in loop_helpers, covering scenarios with and without the gate, escalation leading to parking, and parking failures.
• tests/unit/engine/test_security_factory.py
  • Added new test file for the _security_factory module, covering make_security_interceptor and registry_with_approval_tool functions.
• tests/unit/observability/test_events.py
  • Added approval_gate to the list of expected domain modules for event constant discovery.
• tests/unit/persistence/sqlite/test_migrations_v6.py
  • Updated the schema version check to 7.
• tests/unit/persistence/test_migrations_v2.py
  • Added a test to confirm the schema version is 7.
  • Added tests for the V7 migration, verifying parked_contexts.task_id becomes nullable and existing data is preserved.
• tests/unit/tools/test_approval_tool.py
  • Added new test file for RequestHumanApprovalTool, covering tool creation, execution, parking metadata, risk classification, validation, and error handling.
• tests/unit/tools/test_invoker_escalation.py
  • Added new test file for ToolInvoker escalation tracking, covering empty escalations, ESCALATE verdicts, clearing between calls, multiple escalations, and parking tool metadata.
• web/src/tests/stores/approvals.test.ts
  • Updated WebSocket event handling tests to use approval_id from the payload.
  • Modified tests to simulate fetching full approval items via API after WS events.
  • Added tests for re-fetching filtered queries when filters are active and WS events occur.
  • Added tests for correctly decrementing total count when an item is removed due to a 404/410 from getApproval.
  • Added tests to ensure state is not changed on transient fetch errors during WS event processing.
• web/src/stores/approvals.ts
  • Imported axios for error type checking.
  • Refactored handleWsEvent to use approval_id from the WebSocket payload.
  • Implemented logic to fetch the full approval item via approvalsApi.getApproval for approval.submitted events.
  • Implemented logic to re-fetch the full approval item for approval.approved, approval.rejected, and approval.expired events.
  • Added conditional re-fetching of the entire filtered list if activeFilters are present, ensuring UI consistency.
  • Added error handling for API calls within handleWsEvent, specifically for 404/410 responses to remove items from the local store and decrement the total count.

• The author, Aureliolo, has implemented a significant new feature: approval workflow gates for the TaskEngine.
• Extensive unit tests (7632+ passing, 94.6% coverage) have been added or updated to cover the new functionality, including the approval gate lifecycle, escalation tracking, tool creation, API helpers, and database migrations.
• Architectural decisions regarding resume signalling, external loop wiring, and error handling have been documented and implemented.

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

1. src/ai_company/engine/approval_gate.py, line 74-87 (link)

   Only first escalation is parked — others become permanently orphaned

   When invoke_all fires multiple tools concurrently and more than one triggers ESCALATE or request_human_approval, should_park returns only escalations[0]. The remaining ApprovalItem records are created in the approval store (PENDING) but no ParkedContext is ever saved for them.

   Consequences:

   • A human operator who approves/rejects those extra items triggers _signal_resume_intent, which logs APPROVAL_GATE_RESUME_TRIGGERED.
   • resume_context(approval_id) then calls _parked_context_repo.get_by_approval(approval_id), which returns None (no context was ever parked), so the agent is silently not resumed.
   • The operator gets no error feedback; the approval item stays decided but the agent stays dead.

   At a minimum, should_park should log a warning for every escalation beyond the first, or the store items for those escalations should be auto-rejected/expired to prevent them from appearing as actionable in the UI.

   def should_park(
       self,
       escalations: tuple[EscalationInfo, ...],
   ) -> EscalationInfo | None:
       if not escalations:
           return None
       if len(escalations) > 1:
           logger.warning(
               APPROVAL_GATE_ESCALATION_DETECTED,
               escalation_count=len(escalations),
               first_approval_id=escalations[0].approval_id,
               skipped_ids=[e.approval_id for e in escalations[1:]],
               note=(
                   "Only the first escalation will be parked; "
                   "remaining approval items will not be resumable"
               ),
           )
       else:
           logger.info(
               APPROVAL_GATE_ESCALATION_DETECTED,
               escalation_count=1,
               first_approval_id=escalations[0].approval_id,
           )
       return escalations[0]

2. src/ai_company/tools/approval_tool.py, line 156-181 (link)

   Tool-initiated approval items never expire

   _persist_item creates the ApprovalItem with no expires_at (it defaults to None), so items created by request_human_approval never expire. If an agent parks on an approval and then terminates abnormally — crash, forced stop, deployment replacement — the corresponding ApprovalItem and ParkedContext will remain in PENDING status indefinitely. Over time, stale items accumulate in the queue with no way to correlate them back to a live agent.

   Consider accepting an optional ttl_seconds parameter in the tool's schema (or wiring a default from engine config), and passing it through to the item:

   # In parameters_schema["properties"]:
   "ttl_seconds": {
       "type": "integer",
       "minimum": 60,
       "maximum": 604800,
       "description": "Optional TTL in seconds (default: 24h)",
   },

   # In _persist_item:
   ttl = arguments.get("ttl_seconds")
   expires_at = datetime.now(UTC) + timedelta(seconds=ttl) if ttl else None
   item = ApprovalItem(
       ...
       expires_at=expires_at,
   )

3. web/src/stores/approvals.ts, line 64-130 (link)

   Concurrent WS events can interleave fetchApprovals calls with no cancellation

   The void IIFE fires-and-forgets async work for each incoming WS event. When activeFilters.value is set, status-change events (approved/rejected/expired) trigger await fetchApprovals(activeFilters.value). If two such events arrive in rapid succession (e.g., a batch approve operation), two concurrent fetchApprovals calls race to completion:

   • Response 2 (stale) lands after Response 1 (fresh) → Response 2 overwrites approvals.value with older data.

   The test suite uses flushPromises() with a single settled promise, which prevents exposure of this race in tests.

   A common mitigation is an AbortController / cancellation token keyed on the filter state:

   let pendingFetchController: AbortController | null = null
   
   async function fetchApprovals(filters?: ApprovalFilters) {
     pendingFetchController?.abort()
     const controller = new AbortController()
     pendingFetchController = controller
     // ... pass signal through to axios
   }

   Alternatively, a debounce on the WS-triggered re-fetch would reduce the window significantly.