Import AITURK IDE 1.0.0-beta.1 from Hermes 63279301; preserve MIT license

website/docs/developer-guide/subagent-lifecycle-api.md

@@ -0,0 +1,61 @@
+---
+title: Public Subagent Lifecycle API
+sidebar_label: Subagent lifecycle API
+---
+
+# Public Subagent Lifecycle API
+
+Plugins can launch and supervise fresh Hermes child sessions without importing
+`tools.delegate_tool`, gateway internals, TUI state, or `AIAgent` fields.
+The service resolves its parent from the current agent turn, so it works in
+CLI, gateway, non-interactive, and kanban-worker sessions. Launching outside an
+active agent turn fails closed with `No active Hermes parent session`.
+
+```python
+from agent.subagent_lifecycle import SubagentLaunchRequest
+
+def launch_review(ctx):
+    # Call from a plugin tool or hook while an agent turn is active.
+    service = ctx.subagent_lifecycle
+    handle = service.launch(SubagentLaunchRequest(
+        goal="Review this change for regressions.",
+        context="Only inspect the supplied repository.",
+        role="leaf",
+        correlation_id="review-42",
+        allowed_toolsets=("file",),
+    ))
+    # Persist handle.to_dict() if desired.
+    if service.wait(handle, timeout_seconds=2).timed_out:
+        return handle.to_dict()
+    return service.result(handle)
+```
+
+`SubagentHandle` is serializable and carries a versioned, opaque capability.
+Pass it back to `status`, `wait`, `cancel`, `result`, or `reconnect`; malformed
+or forged handles return `UNKNOWN`/`UNKNOWN_HANDLE` and cannot access a child.
+
+The stable states are `PENDING`, `STARTING`, `RUNNING`, `SUCCEEDED`, `FAILED`,
+`INTERRUPTED`, `CANCEL_REQUESTED`, `CANCELLED`, and `UNKNOWN`.
+
+`cancel(handle, reason=...)` is cooperative: it asks the child agent to
+interrupt at its next safe boundary and returns `CANCEL_REQUESTED`; it never
+claims completion until `wait` or `result` observes a terminal state. Terminal
+results are immutable, idempotent, bounded to 32k characters, omit transcripts
+and hidden reasoning, and include a stable result hash.
+
+This API is lifecycle-managed asynchronous execution. Child construction and
+completion use the same host-owned path as `delegate_task`, including parent
+tool-resolution restoration, memory notification, serialized `subagent_stop`
+hooks, resource cleanup, and child-cost rollup. It does not change the
+synchronous `delegate_task` tool, batch delegation, or its gateway/TUI display.
+The initial implementation retains metadata and terminal results in-process for
+one hour.
+After a process restart, `reconnect` returns `RECONNECT_UNAVAILABLE` and never
+starts a replacement child. Running Python threads also cannot survive process
+exit; callers must treat those handles as interrupted by process exit.
+
+Requests are fail-closed: goal/context/metadata sizes are capped, unknown or
+parent-broadening toolsets are rejected, and per-tool blocks, working-directory
+overrides, and per-launch timeouts are explicitly rejected until Hermes can
+support them without weakening isolation. Use `allowed_toolsets` to narrow a
+child; Hermes's existing unsafe-tool block remains enforced.