feat: Add decision record for HookProviders being too low level for High-Level constructs

[zastrowm]

Description

Re-creation of strands-agents/sdk-python#1427, but in the docs repo. I put it under team for now - I anticipate tenets can go in here later. Once we have a better place for it (and/or want it published) we can move it around. The idea is to have a central place for these documents, and docs is the best place [for now]

---

In doing api bar raising for strands-agents/sdk-python/pull/1424, we determined that HookProvider is a too-low-level interface for exposing directly to integrators. This captures that decision & reasoning in log format and sets us up to record future decisions in a similar way going forward.

See DECISIONS.md on the decision & the format

Type of Change

• Content update/revision

Checklist

• I have read the CONTRIBUTING document
• My changes follow the project's documentation style
• I have tested the documentation locally using mkdocs serve
• Links in the documentation are valid and working

---

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

[dbschmigelski]

Documentation Deployment Complete

Your documentation preview has been successfully deployed!

Preview URL: https://d3ehv1nix5p99z.cloudfront.net/pr-420/

[cagataycali]

Review Summary

This PR adds valuable architectural decision documentation (ADR) for the HookProviders API design decision. This is excellent practice for maintaining project design history.

✅ What's Good

• Decision recording format - Following a structured ADR format helps future contributors understand the "why" behind design choices
• Clear reasoning - The distinction between low-level (HookProvider) and high-level (integrations for frameworks) interfaces is well articulated
• Appropriate location - Placing this under docs/team/ makes sense for internal decision documentation

💡 Suggestions (Non-blocking)

• Consider adding a brief example of what a "high-level integration" might look like versus the HookProvider interface to make the distinction more concrete
• The DECISIONS.md format could benefit from a "Decision Date" field for historical tracking

Status

• CI: ✅ Passing
• Mergeable: ✅ Yes
• Conflicts: None

This is a clean, focused PR that adds valuable documentation. Recommend merging once a maintainer approves.

---

Review by strands-coder autonomous agent 🤖

[cagataycali]

📋 Review Summary

This is an excellent contribution that establishes a Decision Records framework for the Strands Agents project. Having architectural decisions documented in a centralized, versioned format is a best practice that will benefit the project long-term.

✅ What I Like

1. Clear Decision Format: The DECISIONS.md structure with Status, Context, Decision, and Consequences sections follows the widely-adopted ADR (Architecture Decision Record) format.

2. Well-Reasoned Content: The HookProvider decision (#2025-001) explains the rationale clearly - distinguishing between low-level infrastructure (HookProvider) and high-level integration APIs is an important architectural boundary.

3. Forward-Looking: Setting up docs/team/ for internal team documents is a good organizational choice that separates public documentation from internal architectural discussions.

💡 Suggestions for Future Consideration

1. Template Addition: Consider adding a DECISION_TEMPLATE.md file to make it easy for contributors to add new decisions in a consistent format.

2. Index/TOC: As decisions accumulate, a table of contents or index at the top of DECISIONS.md would help navigation.

3. Cross-Linking: Future decisions could reference related PRs/issues using GitHub links for full traceability.

🎯 Recommendation

This PR is ready to merge. The CI passes, the content is well-structured, and it fills an important gap in the project's documentation infrastructure.

---

Review by strands-coder autonomous agent 🤖

autonomous agent testing