docs: add sub-agent tool scoping review + implementation PANL

[JayBeest]

Summary

Adds two documentation files that provide an implementation roadmap
for sub-agent tool scoping (issue #4042):

1. SUBAGENT_TOOL_SCOPING_PANL.md — Phased implementation plan with evidence
2. SUBAGENT_TOOL_SCOPING_CODEBASE_GUIDE.md — Onboarding guide for developers

Scope

This is a documentation-only PR. No code changes are included.

• Covers: sub-agent spawn flow, tool registry, gate chain, MCP integration,
  Fleet worker interaction, and WorkerRuntimeProfile
• Addresses: the gaps identified in feat: Environment-level tool sandboxing for sub-agents (enforce tool_restrictions) #4042, Codewhale not following the constitution #4032, and Add per-sub-agent provider routing #3969 discussions

Not in this slice

This PR does not implement any code changes. Implementation will follow
in separate PRs for each phase (see the PANL document for details).

Builds on

• Existing main branch architecture (v0.8.67)
• Gate chain infrastructure (filter_tool_catalog_for_gates, --disallowed-tools)
• custom role semantics from SUBAGENTS.md
• WorkerRuntimeProfile pattern from v0.8.61: Add first-class permission profiles and nonblocking execution defaults #3211/v0.8.61: Split model-facing runtime capabilities from human-facing mode labels #3213

Related Issues

• Closes: feat: Environment-level tool sandboxing for sub-agents (enforce tool_restrictions) #4042 (Environment-level tool sandboxing)
• References: Codewhale not following the constitution #4032 (Constitution bug), Add per-sub-agent provider routing #3969 (Provider routing)

Validation

• Documents cross-referenced against main branch code
• Line numbers verified (as of 2026-07-07)
• Follows existing docs structure (see docs/ARCHITECTURE.md, docs/CONFIGURATION.md)
• No code changes to validate

Feedback Welcome

I'm learning the workflow and the codebase—happy to adjust, restructure, or even close this PR if the docs belong elsewhere or aren't needed.

All Fine. 🐋

[github-actions]

Thanks @JayBeest for taking the time to contribute.

This repository is observing a maintainer-managed PR intake gate in dry-run mode, so this pull request is staying open. This note helps maintainers prepare the allowlist before any enforcement is considered.

Please read CONTRIBUTING.md for the expected contribution shape. A maintainer can grant recurring PR access by commenting /lgtm on a pull request.

[JayBeest]

Quick note on dependencies:

• Phase 1 is independent and ready to proceed.

• Phase 2 (per-sub-agent tool scoping) will benefit from aligning with Add per-sub-agent provider routing #3969's per-sub-agent config structure, so I'll track that as it lands.

• Phase 3 (MCP server assignment) depends on the MCP refactoring work (v0.8.68 refactor(mcp): move McpConnection/McpPool out of mcp.rs #4083, feat: add dynamic MCP server infrastructure to McpPool #3869), so I'll wait for those to crystallize before diving in.

Plan: Phase 1 → watch #3969 → Phase 2 → watch MCP → Phase 3 → 🐋.