Allow extensions to customize automatic session naming safely

[alejandro-ao]

Summary

Allow Tau extensions to customize the automatic name assigned to a new managed session after its first user message is persisted.

Today, automatic naming is owned entirely by tau_coding.session.CodingSession: _try_auto_name_session() calls the active provider/model through _generate_session_name(), sanitizes the result, falls back to a local title when needed, and persists it through _set_auto_session_title(). Extensions can observe session_info_changed, but there is no supported interception hook, naming strategy registration, or public title setter.

Add a narrowly scoped extension seam—tentatively a session_naming hook—that can supply a title before Tau makes its default naming request. Keep this policy in tau_coding; tau_agent should remain independent of session metadata and extensions.

Desired behavior

• An extension can inspect a constrained naming event, including the first persisted user message, and either:
  • return a candidate title, causing Tau to skip its default provider-backed naming request; or
  • defer, preserving the existing model-generated title and local fallback behavior.
• Tau remains responsible for title validation/sanitization, persistence, event emission, and the rule that an existing/manual title is never overwritten.
• The hook runs only when the current auto-naming eligibility checks pass: a managed, unnamed session with exactly its first user message durably persisted.
• Multiple handlers have documented deterministic semantics. A reasonable default is “first valid override wins”; handlers that defer allow the next handler or Tau's default implementation to run.
• Hook failures and unusable results are isolated and diagnosed without interrupting the agent turn; Tau then continues to the next handler or existing fallback path.
• The feature behaves consistently in TUI and print mode because it belongs to the coding-session/runtime layer, not a frontend.

Security and billing guardrail

The hook must not become a general-purpose model invocation API backed by Tau's active provider, the user's subscription token, or API credentials. In particular, do not pass the raw provider, credential store, access token, or an unrestricted generate(prompt) callback to extension code. Such a capability would let a hook make arbitrary requests at the user's expense and would expand the supported credential/trust boundary beyond session naming.

The initial contract should preferably be a pure override: Tau passes minimal naming input and accepts a title/defer result. An extension may use its own explicitly configured services, but Tau should not implicitly authorize arbitrary inference with the user's credentials. If model-assisted custom strategies are considered necessary, design a separately reviewed, constrained capability with explicit user consent, bounded requests, cancellation/timeouts, usage visibility, and clear attribution.

This guardrail complements—not replaces—the existing warning that extensions execute arbitrary Python. The concern here is avoiding a new supported API that makes credential-backed arbitrary model use easy or accidental.

Notes / questions

Proposed API shape

Possible frozen dataclasses in tau_coding.extensions:

@dataclass(frozen=True, slots=True)
class SessionNamingEvent:
    first_message: str

@dataclass(frozen=True, slots=True)
class SessionNamingHookResult:
    title: str | None = None  # None means defer

Example:

def setup(tau):
    @tau.on("session_naming")
    def name_session(event, context):
        return SessionNamingHookResult(title=local_naming_rule(event.first_message))

Questions to settle before implementation:

• Should the API be an intercepting on("session_naming") hook or a single naming-strategy registration? A hook matches the current runtime, while a single strategy may make ownership/conflicts clearer.
• Should handlers receive only first_message, or also non-sensitive read-only metadata such as model/provider names? Start minimal unless a concrete use case requires more.
• Should blank/invalid titles mean “defer” or produce a diagnostic before deferring?
• Should first-valid or last-valid override win? First-valid aligns with Tau's first-registration precedence and avoids unnecessary handler work.
• Should async handlers be supported with a host-enforced timeout? Existing event handlers may be async, but naming must not indefinitely delay the first turn.
• Is a separate public rename_session() API needed? It is not required for auto-naming customization and should be evaluated separately because it permits title changes throughout a session rather than only at the guarded naming point.

Likely implementation areas

• src/tau_coding/session.py: invoke the extension seam after durable first-message persistence and before _generate_session_name(); preserve _should_auto_name_session(), sanitization, fallback, and no-overwrite checks.
• src/tau_coding/extensions/api.py and runtime.py: define the event/result contract, registration/dispatch semantics, failure isolation, and generation/reload behavior.
• src/tau_coding/extensions/__init__.py: export public payload/result types.
• tests/test_extensions.py and tests/test_coding_session.py: deterministic runtime and integration coverage using fake providers.
• website/content/guides/extensions.md: document usage, precedence, lifecycle, and the credential/billing boundary.
• dev-notes/: record the design, security ruling, Pi comparison, and verification commands.

Acceptance criteria

• A supported extension API can return a custom automatic title for the first persisted user message of an eligible managed session.
• A valid extension override is sanitized and persisted by Tau, and the default provider naming request is not made.
• If all handlers defer, existing provider-backed generation and local fallback behavior remain unchanged.
• Exceptions, timeouts (if async handlers are supported), and invalid titles cannot interrupt the agent turn; they produce bounded diagnostics and fall back safely.
• Existing/manual session titles are never overwritten, and unmanaged or already-named sessions do not invoke the hook.
• Multiple extensions/handlers follow documented, deterministic precedence.
• The public hook does not expose provider objects, credentials/tokens, the credential store, or an unrestricted credential-backed model invocation callback.
• Tests prove that an override avoids the provider naming call and that defer/error/invalid/manual-title paths preserve current behavior.
• Extension reload/stale-generation behavior is covered where relevant.
• Published extension docs and a beginner-friendly development note describe the API, examples, trust boundary, billing risk, and verification steps.
• Focused tests plus the repository's pytest, Ruff, formatting, and mypy checks pass.

[chiruu12]

Hi @alejandro-ao, I'd like to take this as a focused first slice. I plan to add a pure session_naming override hook that receives only the first persisted user message, uses first-valid-handler-wins semantics, supports the existing sync/async handler model with a host-enforced timeout, keeps sanitization, persistence, and fallback in CodingSession, and never exposes providers or credentials. I'll cover override, defer, error, timeout, invalid result, manual-title, and reload paths with fake-provider tests, then update the extension docs and add a short design note. A general rename API and credential-backed model callbacks would stay out of scope, and I will rebase around #480 if it lands. Does that scope match what you want?