feat(engine): give the model actionable detail on a failed child-agent call

[AmitAvital1]

Stacked on #76 — please review/merge that one first.

What

#76 made a failed child-agent call recoverable instead of crashing the run, but the model only got a generic notice back ("Agent 'X' failed to complete this request. This is an internal error, not a problem with the arguments."). A model can't correct a call it can't read the failure of.

This PR replaces that generic notice with actionable detail:

• Validation failures (malformed tool args) are reworded via validation_problems()/_invalid_args_message() into field-level detail — which fields were wrong and why — without echoing the rejected arguments back into the model's own context.
• Any other child failure now passes its safe_error()-bounded cause through to the model (_child_failure_message()) — the same contract a regular tool failure already has with its caller — instead of a message that gives the model nothing to act on.
• _AgentCall.message gets a schema description clarifying it's a single plain-text string, reducing how often the orchestrator sends a shape that would only fail validation in the first place.

Test plan

• test_orchestrator_recovers_from_invalid_child_tool_args — asserts the model sees field-level detail ("Invalid arguments for 'flights': message: Input should be a valid string") and that the rejected argument value never reaches the model's context or any log field.
• test_orchestrator_recovers_from_child_agent_crash — updated to assert the actual cause ("Model execution failed") reaches the model instead of a generic notice.
• make lint, make typecheck, make test all pass

🤖 Generated with Claude Code

[AmitAvital1]

Stacked on #76 — please review/merge that one first.

What

#76 made a failed child-agent call recoverable instead of crashing the run, but the model only got a generic notice back ("Agent 'X' failed to complete this request. This is an internal error, not a problem with the arguments."). A model can't correct a call it can't read the failure of.

This PR replaces that generic notice with actionable detail:

• Validation failures (malformed tool args) are reworded via validation_problems()/_invalid_args_message() into field-level detail — which fields were wrong and why — without echoing the rejected arguments back into the model's own context.
• Any other child failure now passes its safe_error()-bounded cause through to the model (_child_failure_message()) — the same contract a regular tool failure already has with its caller — instead of a message that gives the model nothing to act on.
• _AgentCall.message gets a schema description clarifying it's a single plain-text string, reducing how often the orchestrator sends a shape that would only fail validation in the first place.

Test plan

• test_orchestrator_recovers_from_invalid_child_tool_args — asserts the model sees field-level detail ("Invalid arguments for 'flights': message: Input should be a valid string") and that the rejected argument value never reaches the model's context or any log field.
• test_orchestrator_recovers_from_child_agent_crash — updated to assert the actual cause ("Model execution failed") reaches the model instead of a generic notice.
• make lint, make typecheck, make test all pass

🤖 Generated with Claude Code

[AmitAvital1]

Stacked on #76 — please review/merge that one first.

What

#76 made a failed child-agent call recoverable instead of crashing the run, but the model only got a generic notice back ("Agent 'X' failed to complete this request. This is an internal error, not a problem with the arguments."). A model can't correct a call it can't read the failure of.

This PR replaces that generic notice with actionable detail:

• Validation failures (malformed tool args) are reworded via validation_problems()/_invalid_args_message() into field-level detail — which fields were wrong and why — without echoing the rejected arguments back into the model's own context.
• Any other child failure now passes its safe_error()-bounded cause through to the model (_child_failure_message()) — the same contract a regular tool failure already has with its caller — instead of a message that gives the model nothing to act on.
• _AgentCall.message gets a schema description clarifying it's a single plain-text string, reducing how often the orchestrator sends a shape that would only fail validation in the first place.

Test plan

• test_orchestrator_recovers_from_invalid_child_tool_args — asserts the model sees field-level detail ("Invalid arguments for 'flights': message: Input should be a valid string") and that the rejected argument value never reaches the model's context or any log field.
• test_orchestrator_recovers_from_child_agent_crash — updated to assert the actual cause ("Model execution failed") reaches the model instead of a generic notice.
• make lint, make typecheck, make test all pass

🤖 Generated with Claude Code

[AmitAvital1]

Stacked on #76 — please review/merge that one first.

What

#76 made a failed child-agent call recoverable instead of crashing the run, but the model only got a generic notice back ("Agent 'X' failed to complete this request. This is an internal error, not a problem with the arguments."). A model can't correct a call it can't read the failure of.

This PR replaces that generic notice with actionable detail:

• Validation failures (malformed tool args) are reworded via validation_problems()/_invalid_args_message() into field-level detail — which fields were wrong and why — without echoing the rejected arguments back into the model's own context.
• Any other child failure now passes its safe_error()-bounded cause through to the model (_child_failure_message()) — the same contract a regular tool failure already has with its caller — instead of a message that gives the model nothing to act on.
• _AgentCall.message gets a schema description clarifying it's a single plain-text string, reducing how often the orchestrator sends a shape that would only fail validation in the first place.

Test plan

• test_orchestrator_recovers_from_invalid_child_tool_args — asserts the model sees field-level detail ("Invalid arguments for 'flights': message: Input should be a valid string") and that the rejected argument value never reaches the model's context or any log field.
• test_orchestrator_recovers_from_child_agent_crash — updated to assert the actual cause ("Model execution failed") reaches the model instead of a generic notice.
• make lint, make typecheck, make test all pass

🤖 Generated with Claude Code

[AmitAvital1]

Stacked on #76 — please review/merge that one first.

What

#76 made a failed child-agent call recoverable instead of crashing the run, but the model only got a generic notice back ("Agent 'X' failed to complete this request. This is an internal error, not a problem with the arguments."). A model can't correct a call it can't read the failure of.

This PR replaces that generic notice with actionable detail:

• Validation failures (malformed tool args) are reworded via validation_problems()/_invalid_args_message() into field-level detail — which fields were wrong and why — without echoing the rejected arguments back into the model's own context.
• Any other child failure now passes its safe_error()-bounded cause through to the model (_child_failure_message()) — the same contract a regular tool failure already has with its caller — instead of a message that gives the model nothing to act on.
• _AgentCall.message gets a schema description clarifying it's a single plain-text string, reducing how often the orchestrator sends a shape that would only fail validation in the first place.

Test plan

• test_orchestrator_recovers_from_invalid_child_tool_args — asserts the model sees field-level detail ("Invalid arguments for 'flights': message: Input should be a valid string") and that the rejected argument value never reaches the model's context or any log field.
• test_orchestrator_recovers_from_child_agent_crash — updated to assert the actual cause ("Model execution failed") reaches the model instead of a generic notice.
• make lint, make typecheck, make test all pass

🤖 Generated with Claude Code

[AmitAvital1]

Stacked on #76 — please review/merge that one first.

What

#76 made a failed child-agent call recoverable instead of crashing the run, but the model only got a generic notice back ("Agent 'X' failed to complete this request. This is an internal error, not a problem with the arguments."). A model can't correct a call it can't read the failure of.

This PR replaces that generic notice with actionable detail:

• Validation failures (malformed tool args) are reworded via validation_problems()/_invalid_args_message() into field-level detail — which fields were wrong and why — without echoing the rejected arguments back into the model's own context.
• Any other child failure now passes its safe_error()-bounded cause through to the model (_child_failure_message()) — the same contract a regular tool failure already has with its caller — instead of a message that gives the model nothing to act on.
• _AgentCall.message gets a schema description clarifying it's a single plain-text string, reducing how often the orchestrator sends a shape that would only fail validation in the first place.

Test plan

• test_orchestrator_recovers_from_invalid_child_tool_args — asserts the model sees field-level detail ("Invalid arguments for 'flights': message: Input should be a valid string") and that the rejected argument value never reaches the model's context or any log field.
• test_orchestrator_recovers_from_child_agent_crash — updated to assert the actual cause ("Model execution failed") reaches the model instead of a generic notice.
• make lint, make typecheck, make test all pass

🤖 Generated with Claude Code

[AmitAvital1]

Stacked on #76 — please review/merge that one first.

What

#76 made a failed child-agent call recoverable instead of crashing the run, but the model only got a generic notice back ("Agent 'X' failed to complete this request. This is an internal error, not a problem with the arguments."). A model can't correct a call it can't read the failure of.

This PR replaces that generic notice with actionable detail:

• Validation failures (malformed tool args) are reworded via validation_problems()/_invalid_args_message() into field-level detail — which fields were wrong and why — without echoing the rejected arguments back into the model's own context.
• Any other child failure now passes its safe_error()-bounded cause through to the model (_child_failure_message()) — the same contract a regular tool failure already has with its caller — instead of a message that gives the model nothing to act on.
• _AgentCall.message gets a schema description clarifying it's a single plain-text string, reducing how often the orchestrator sends a shape that would only fail validation in the first place.

Test plan

• test_orchestrator_recovers_from_invalid_child_tool_args — asserts the model sees field-level detail ("Invalid arguments for 'flights': message: Input should be a valid string") and that the rejected argument value never reaches the model's context or any log field.
• test_orchestrator_recovers_from_child_agent_crash — updated to assert the actual cause ("Model execution failed") reaches the model instead of a generic notice.
• make lint, make typecheck, make test all pass

🤖 Generated with Claude Code

[AmitAvital1]

Stacked on #76 — please review/merge that one first.

What

#76 made a failed child-agent call recoverable instead of crashing the run, but the model only got a generic notice back ("Agent 'X' failed to complete this request. This is an internal error, not a problem with the arguments."). A model can't correct a call it can't read the failure of.

This PR replaces that generic notice with actionable detail:

• Validation failures (malformed tool args) are reworded via validation_problems()/_invalid_args_message() into field-level detail — which fields were wrong and why — without echoing the rejected arguments back into the model's own context.
• Any other child failure now passes its safe_error()-bounded cause through to the model (_child_failure_message()) — the same contract a regular tool failure already has with its caller — instead of a message that gives the model nothing to act on.
• _AgentCall.message gets a schema description clarifying it's a single plain-text string, reducing how often the orchestrator sends a shape that would only fail validation in the first place.

Test plan

• test_orchestrator_recovers_from_invalid_child_tool_args — asserts the model sees field-level detail ("Invalid arguments for 'flights': message: Input should be a valid string") and that the rejected argument value never reaches the model's context or any log field.
• test_orchestrator_recovers_from_child_agent_crash — updated to assert the actual cause ("Model execution failed") reaches the model instead of a generic notice.
• make lint, make typecheck, make test all pass

🤖 Generated with Claude Code