Deprecate and remove custom Jinja system prompt fallback

Context

PR #3910 ports the last built-in planning prompt to the typed prompt registry and keeps system_prompt_planning.j2 only as a back-compat sentinel filename. The built-in prompt templates are gone, but AgentBase still intentionally preserves the Jinja escape hatch for custom system_prompt_filename values and subclasses with custom prompt_dir values.

That fallback is useful for compatibility today, but it keeps a second prompt-rendering engine alive after the built-in prompts have moved to the registry.

Proposal

Deprecate, then remove, the custom .j2 system-prompt fallback path in favor of typed prompt-registry composition and/or explicit inline system_prompt overrides.

Suggested scope:

• Define the supported replacement path for downstream users who currently provide custom Jinja templates.
• Add a deprecation warning when AgentBase takes the custom Jinja fallback path.
• Document the migration path from custom .j2 templates to registry sections/presets or inline prompts.
• After the SDK deprecation runway, remove the custom .j2 fallback and any Jinja-only prompt plumbing that is no longer needed.

Acceptance criteria

• Custom Jinja prompt usage has a documented deprecation notice and removal target consistent with the SDK compatibility policy.
• Users have a clear migration path that preserves legitimate customization use cases.
• Built-in sentinel filenames such as system_prompt.j2 / system_prompt_planning.j2 continue to resolve compatibly until their own compatibility runway is complete.
• The final removal eliminates the custom Jinja fallback without reintroducing a parallel built-in prompt rendering path.

Requested from review discussion on #3910: https://github.com/OpenHands/software-agent-sdk/pull/3910#discussion_r3495552833

This issue was created by an AI agent (OpenHands) on behalf of the PR author in response to reviewer feedback.

Start by reviewing AgentBase and the handling of custom system_prompt_filename and prompt_dir values, then read the compatibility discussion in PR #3910. Trace the custom .j2 fallback and sentinel filenames such as system_prompt.j2 and system_prompt_planning.j2. Done means the deprecation notice, migration documentation, compatibility runway, and eventual removal scope are defined without disrupting supported sentinel behavior.