feat(audit): add structured policy metadata to tool call results

[gapliu54-lab]

Summary

This PR adds structured audit/policy metadata to ToolCallResult so downstream observability and governance tooling can reason about what happened and why in a machine-readable way.

What changed

1) Extended ToolCallResult shape (src/types.ts)

Added optional fields:

• riskLevel
• policyDecision (allow | block | require_confirmation | dry_run)
• policyReason
• capability

These are optional to preserve backward compatibility.

2) Annotated tool execution path (src/agent/tools.ts)

In executeTool(...):

• Unknown tool path now returns structured policy metadata (block, reason, capability).
• Policy-evaluated path maps engine action to normalized policyDecision.
• Success and error returns now include:
  • tool risk level
  • policy decision label
  • policy reason
  • capability namespace

Also introduced a small capability mapper for high-impact tools (finance/network/domain/self-mod) and a category-based fallback for others.

3) Documentation update (README.md)

Added a new section:

• Audit event fields (risk/policy)
• includes a JSON example showing expected metadata.

Why

Automaton already has policy + audit mechanisms. This PR makes policy outcomes explicit in tool results so operators and future policy gates can:

• filter critical events,
• build clearer audit trails,
• analyze decision quality over time,
• reduce ambiguity in incident review.

Backward compatibility

• Existing consumers are not broken: fields are additive and optional.

Validation

• npx tsc -p tsconfig.json --noEmit passes locally.

Follow-ups (not in this PR)

• enforce secure-by-default policy gates for high-risk capabilities,
• add per-capability baseline policy profiles,
• include these fields in persistent policy decision logs if needed.