docs: add architecture review record for issue 217

[fennoai]

Requested by @Cai-Tang-www

Summary

• add docs/architecture-review-issue-217.md
• record the architecture review findings gathered for issue 查错查架构 #217
• keep the current branch scope limited to documentation only

Verification

• not run (docs only)

[codecov]

Codecov Report

❌ Patch coverage is 71.42857% with 18 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
internal/runtime/runtime.go	54.54%	5 Missing and 5 partials ⚠️
internal/runtime/permission.go	82.60%	2 Missing and 2 partials ⚠️
internal/tools/manager.go	77.77%	4 Missing ⚠️

📢 Thoughts on this report? Let us know!

[fennoai]

I found a few documentation-accuracy issues where the review record overstates the current code evidence or mischaracterizes behavior.

[fennoai]

This section currently treats internal/gateway as if it were only an unused abstraction layer, but the package also contains concrete protocol assets in types.go, validate.go, and errors.go with coverage in internal/gateway/*_test.go. If the concern is specifically the unused Gateway/RuntimePort contracts, please scope the criticism to that port/interface layer; otherwise the recommendation to delete the whole package is broader than the code here supports.

[fennoai]

NoopWorkspaceSandbox is weaker than the real workspace sandbox, but this sentence overstates the effect. With call.WorkspacePlan == nil, the tools still enforce workspace-root boundaries through ResolveWorkspaceTarget and per-tool path/workdir checks, so this is not equivalent to unrestricted execution. The more accurate risk is loss of the extra centralized hardening in security.NewWorkspaceSandbox() such as canonical-root, symlink-escape, and execution-time revalidation checks.

[fennoai]

This wording is a bit too broad. emit does not drop events just because the channel is full; it retries and only returns an error when the run context is canceled before the send can complete. Narrowing this section to cancellation/backpressure-induced failures would make the runtime analysis more precise.