A prompt injection vulnerability exists because the AgentEngine constructs prompts by directly concatenating fields from the Task and AgentIdentity objects without any sanitization or escaping. If an attacker controls Task or AgentIdentity fields (e.g., title, description, acceptance_criteria, name, personality.description), they can inject malicious instructions, potentially leading to LLM manipulation, unauthorized tool execution, or data exfiltration. Remediation requires implementing sanitization or escaping for all untrusted inputs, considering structured prompt formats or LLM-based guardrails, and instructing the LLM to treat user-provided task data as untrusted. (Also, note a minor formatting inconsistency: the deadline section lacks a blank line before it, unlike the budget limit section, which can reduce readability.)

The AgentEngine constructs prompts by directly concatenating fields from the Task and AgentIdentity objects without any sanitization or escaping. Specifically, in _prepare_context, the task and identity objects are passed to build_system_prompt to create the system prompt, and the task object is passed to _format_task_instruction to create the initial user message. If an attacker can control the fields of the Task (e.g., title, description, acceptance_criteria) or AgentIdentity (e.g., name, personality.description), they can inject malicious instructions into the prompt. This can lead to manipulation of the LLM's behavior, unauthorized tool execution, or exfiltration of sensitive information.

To remediate this, implement sanitization or escaping for all untrusted inputs included in prompts. Consider using structured prompt formats or LLM-based guardrails to detect and prevent prompt injection. Ensure that the LLM is instructed to treat user-provided task data as untrusted content.

For consistency with other files in this PR (e.g., agent_engine.py), type-only imports should be placed within a TYPE_CHECKING block. This avoids using noqa suppressions and is a standard practice for handling circular dependencies and improving startup time. You would also need to update the type hints in the class to be string forward references (e.g., agent_id: "NotBlankStr").

For consistency with other files in this PR (e.g., agent_engine.py), type-only imports should be placed within a TYPE_CHECKING block. This avoids using noqa suppressions. You would also need to update the type hints in function signatures to be string forward references (e.g., sample_agent_with_personality: "AgentIdentity").

Both except clauses use except MemoryError, RecursionError: which is invalid Python 3 syntax. In Python 3, this is a SyntaxError. The correct syntax for catching multiple exception types is except (MemoryError, RecursionError):. Without the parentheses, this code will fail to parse entirely and cannot be imported or executed.

The correct pattern, consistent with how it is used elsewhere in the codebase (e.g., src/ai_company/tools/invoker.py), is except (MemoryError, RecursionError):.

Same invalid Python 3 syntax as at line 138: except MemoryError, RecursionError: is a SyntaxError in Python 3. It must be written as except (MemoryError, RecursionError): to correctly catch both MemoryError and RecursionError and re-raise them.

The PR description states "4 new execution event constants for debug observability (EXECUTION_ENGINE_CREATED, EXECUTION_ENGINE_PROMPT_BUILT, EXECUTION_ENGINE_COST_SKIPPED, EXECUTION_ENGINE_COST_FAILED)", but the diff actually adds 10 new constants: EXECUTION_ENGINE_CREATED, EXECUTION_ENGINE_START, EXECUTION_ENGINE_PROMPT_BUILT, EXECUTION_ENGINE_COMPLETE, EXECUTION_ENGINE_ERROR, EXECUTION_ENGINE_INVALID_INPUT, EXECUTION_ENGINE_TASK_TRANSITION, EXECUTION_ENGINE_COST_RECORDED, EXECUTION_ENGINE_COST_SKIPPED, and EXECUTION_ENGINE_COST_FAILED. The PR description should be updated to reflect the actual number of new constants added.

The deadline is appended without a blank-line separator before it, while budget_limit inserts an empty string (parts.append("")) before it for spacing. When a deadline exists but budget_limit is 0 (or negative), the deadline immediately follows the description or last acceptance criterion with no blank line, resulting in inconsistent markdown formatting compared to the budget block.

The codebase consistently includes a test_frozen test for every frozen Pydantic model (e.g., TurnRecord, ExecutionResult, SystemPrompt, AgentContext, TaskExecution, etc. all have dedicated test_frozen cases). The AgentRunResult model uses model_config = ConfigDict(frozen=True) but test_agent_engine.py does not include a corresponding test_frozen test. A test that attempts to reassign a field and expects a ValidationError should be added, consistent with the convention established throughout the engine test suite.

⚠️ Potential issue | 🟡 Minor

Section 15.3 now contradicts itself.

The note above this tree says milestone-tagged files are planned-only, but agent_engine.py is still tagged (M3) even though this PR adds it. Please either drop milestone tags from shipped files or rewrite the note so readers can tell which engine modules actually exist.

Based on learnings, "When making changes that affect architecture, services, key files, settings, or workflows, update the relevant sections of existing documentation (CLAUDE.md, README.md, etc.) to reflect those changes."

Verify each finding against the current code and only fix it if needed.

In `@DESIGN_SPEC.md` around lines 2155 - 2156, Section 15.3's "planned-only" note
conflicts with the file tree because agent_engine.py is listed with a milestone
tag (M3) but the PR actually adds that file; update the doc so readers can tell
which modules exist now by either removing milestone tags from files that are
already shipped (remove "(M3)" from agent_engine.py and any other added files
like run_result.py if shipped) or rewrite the note to state that milestone tags
indicate original plan (not current presence) and explicitly mark planned-only
files (e.g., add "(planned)" or a separate subsection). Also update any
cross-references mentioned (CLAUDE.md, README.md) to reflect the corrected
status of agent_engine.py and related engine modules.

⚠️ Potential issue | 🟠 Major

Validate max_turns before entering the generic error wrapper.

Line 94 exposes max_turns, but the first real validation happens later inside AgentContext.from_identity(). Today max_turns <= 0 gets caught by the broad except Exception path and comes back as TerminationReason.ERROR, which turns bad caller input into a runtime engine failure instead of rejecting it at the boundary.

         agent_id = str(identity.id)
         task_id = task.id
 
+        if max_turns <= 0:
+            msg = f"max_turns must be greater than 0, got {max_turns}"
+            logger.warning(
+                EXECUTION_ENGINE_INVALID_INPUT,
+                agent_id=agent_id,
+                task_id=task_id,
+                reason=msg,
+            )
+            raise ValueError(msg)
+
         self._validate_agent(identity, agent_id)
         self._validate_task(task, agent_id, task_id)

As per coding guidelines, "Validate at system boundaries (user input, external APIs, config files)".

Verify each finding against the current code and only fix it if needed.

In `@src/ai_company/engine/agent_engine.py` around lines 94 - 148, Validate the
incoming max_turns at the start of the method (before the try/except that wraps
_execute) so invalid caller input (e.g., max_turns <= 0) is rejected at the
boundary rather than being converted into a fatal engine error; add a short
check right after agent_id/task_id assignment that raises a clear user-level
exception (e.g., ValueError with a concise message) when max_turns is not
positive, keeping references to the existing symbols _execute,
_handle_fatal_error, and AgentContext.from_identity to locate the related logic.

⚠️ Potential issue | 🟠 Major

Preserve the prepared context/prompt on fatal errors.

Once _prepare_context() succeeds, any later exception still falls through to _handle_fatal_error(), which rebuilds a blank AgentContext and synthetic prompt at Lines 400-412. That drops the seeded conversation, the caller-supplied max_turns, and the ASSIGNED -> IN_PROGRESS transition, so the returned AgentRunResult can report misleading state after execution has already started.

Catch the post-setup failure path inside _execute() and thread the prepared ctx / system_prompt into _handle_fatal_error() when they already exist.

Also applies to: 381-419

Verify each finding against the current code and only fix it if needed.

In `@src/ai_company/engine/agent_engine.py` around lines 162 - 212, After
successfully calling _prepare_context (which returns ctx and system_prompt)
modify _execute so any exceptions raised after that point are caught and
forwarded to _handle_fatal_error with the original ctx and system_prompt instead
of letting _handle_fatal_error rebuild a blank AgentContext; specifically wrap
the post-_prepare_context work (including creation of
budget_checker/tool_invoker, the await self._loop.execute call, _record_costs,
and construction of AgentRunResult) in a try/except that calls
_handle_fatal_error(exception, ctx=ctx, system_prompt=system_prompt, ...) to
preserve the seeded conversation, max_turns and ASSIGNED->IN_PROGRESS state when
returning the AgentRunResult.

The deadline section is missing the blank-line separator that the budget section includes. When both budget and deadline are present, they will render on consecutive lines with no visual separation. When only deadline is present, it butts directly against the preceding section.

This ensures consistent Markdown formatting across all task instruction blocks.

This is a comment left during a code review.
Path: src/ai_company/engine/agent_engine.py
Line: 435-436

Comment:
The deadline section is missing the blank-line separator that the budget section includes. When both budget and deadline are present, they will render on consecutive lines with no visual separation. When only deadline is present, it butts directly against the preceding section.

```suggestion
    if task.deadline:
        parts.append("")
        parts.append(f"**Deadline:** {task.deadline}")
```

This ensures consistent Markdown formatting across all task instruction blocks.

How can I resolve this? If you propose a fix, please make it concise.