Release v4.6.162

docs: auto-update feature parity trackers [skip ci]
Merge pull request #3865 from MervinPraison/claude/issue-3864-20260811-1714
2026-11-07 17:33:33 -10:00 · 2026-08-13 00:20:05 +00:00 · 2026-08-11 18:46:24 +00:00 · 2026-08-11 18:45:55 +00:00 · 2026-08-11 17:16:10 +00:00 · 2026-08-11 10:41:08 +00:00
740 changed files with 71268 additions and 8362 deletions
@@ -1,5 +1,5 @@
 name: Install PraisonAI monorepo packages
-description: Install praisonai-agents, praisonai-code, praisonai-bot, praisonai-train, praisonai-browser, praisonai-mcp, praisonai-sandbox, and praisonai wrapper from local paths (mirrors PyPI eight-package install order).
+description: Install praisonai-agents, praisonai-code, praisonai-bot, praisonai-train, praisonai-browser, praisonai-mcp, praisonai-sandbox, praisonai-deploy, and praisonai wrapper from local paths (mirrors PyPI nine-package install order).

 inputs:
  repo-root:
@@ -40,6 +40,7 @@ runs:
        BROWSER_PKG="${BASE}src/praisonai-browser"
        MCP_PKG="${BASE}src/praisonai-mcp"
        SANDBOX_PKG="${BASE}src/praisonai-sandbox"
+        DEPLOY_PKG="${BASE}src/praisonai-deploy"
        WRAPPER_PKG="${BASE}src/praisonai"

        normalise_extras() {
@@ -69,6 +70,8 @@ runs:
          uv pip install --system -e .
          cd "$SANDBOX_PKG"
          uv pip install --system -e .
+          cd "$DEPLOY_PKG"
+          uv pip install --system -e .
          cd "$WRAPPER_PKG"
          uv pip install --system "${WRAPPER_SUFFIX}"
        else
@@ -86,6 +89,8 @@ runs:
          pip install -e .
          cd "$SANDBOX_PKG"
          pip install -e .
+          cd "$DEPLOY_PKG"
+          pip install -e .
          cd "$WRAPPER_PKG"
          pip install -e "${WRAPPER_SUFFIX}"
        fi
@@ -11,47 +11,112 @@ assert.ok(versions.currentCode);
 assert.ok(versions.currentWrapper);
 assert.ok(versions.targetCode);
 assert.ok(rg.PACKAGE_PATHS.includes('src/praisonai-code'));
+// Every released package must make the gate's path-change check eligible.
+for (const p of [
+  'src/praisonai', 'src/praisonai-agents', 'src/praisonai-code',
+  'src/praisonai-bot', 'src/praisonai-train', 'src/praisonai-browser',
+  'src/praisonai-mcp', 'src/praisonai-sandbox', 'src/praisonai-deploy',
+]) {
+  assert.ok(rg.PACKAGE_PATHS.includes(p), `PACKAGE_PATHS missing ${p}`);
+}

 const noonUtc = new Date('2026-07-08T12:00:00Z');
 const dayStart = rg.utcDayStart(noonUtc);
 assert.strictEqual(dayStart.toISOString(), '2026-07-08T00:00:00.000Z');

-(async () => {
-  assert.strictEqual(await rg.pypiVersionExists('praisonaiagents', '0.0.0'), false);
-
-  const mockGithub = {
+function mockGithub({ runs = [], releases = [] } = {}) {
+  return {
    rest: {
      actions: {
-        listWorkflowRuns: async () => ({
-          data: {
-            workflow_runs: [
-              {
-                conclusion: 'success',
-                created_at: '2026-07-08T09:00:00Z',
-                status: 'completed',
-              },
-            ],
-          },
-        }),
+        listWorkflowRuns: async () => ({ data: { workflow_runs: runs } }),
+      },
+      repos: {
+        listReleases: async () => ({ data: releases }),
      },
    },
  };
+}
+
+(async () => {
+  assert.strictEqual(await rg.pypiVersionExists('praisonaiagents', '0.0.0'), false);
+
+  assert.strictEqual(rg.PATCH_RELEASE_INTERVAL_DAYS, 3);
+
+  // Dedupe is release-based: a v* release inside the window blocks…
+  const recentRelease = mockGithub({
+    releases: [{ tag_name: 'v4.6.159', published_at: '2026-07-08T09:00:00Z' }],
+  });
  assert.strictEqual(
-    await rg.hasSuccessfulReleaseToday(mockGithub, 'o', 'r', noonUtc),
+    await rg.hasSuccessfulReleaseWithinDays(recentRelease, 'o', 'r', noonUtc),
    true
  );

  const result = await rg.evaluateReleasePreflight(
-    mockGithub, 'o', 'r',
+    recentRelease, 'o', 'r',
    { headSha: 'abc', isCiTrigger: false, bump: 'patch', now: noonUtc },
    null
  );
-  assert.ok(result.reasons.some((r) => r.includes('already released today')));
+  assert.ok(result.reasons.some((r) => r.includes('every 3 days')));
+
+  // …an old release does not…
+  const oldRelease = mockGithub({
+    releases: [{ tag_name: 'v4.6.150', published_at: '2026-07-04T09:00:00Z' }],
+  });
+  assert.strictEqual(
+    await rg.hasSuccessfulReleaseWithinDays(oldRelease, 'o', 'r', noonUtc),
+    false
+  );
+
+  // …and a dry-run "success" (workflow run, no release) does not consume the
+  // window: only real releases count.
+  const dryRunOnly = mockGithub({
+    runs: [{ conclusion: 'success', created_at: '2026-07-08T09:00:00Z', status: 'completed' }],
+    releases: [],
+  });
+  assert.strictEqual(
+    await rg.hasSuccessfulReleaseWithinDays(dryRunOnly, 'o', 'r', noonUtc),
+    false
+  );
+
+  // Active-run blocking: fresh waiting run blocks…
+  const freshWaiting = mockGithub({
+    runs: [{ status: 'waiting', conclusion: null, created_at: '2026-07-08T11:00:00Z', html_url: 'x' }],
+  });
+  assert.strictEqual(
+    await rg.hasActiveReleaseRun(freshWaiting, 'o', 'r', noonUtc, null),
+    true
+  );
+
+  // …a waiting run stuck longer than STALE_WAITING_HOURS no longer blocks…
+  const staleWaiting = mockGithub({
+    runs: [{ status: 'waiting', conclusion: null, created_at: '2026-07-08T01:00:00Z', html_url: 'x' }],
+  });
+  const warnings = [];
+  const fakeCore = { warning: (m) => warnings.push(m), info: () => {} };
+  assert.strictEqual(rg.STALE_WAITING_HOURS, 6);
+  assert.strictEqual(
+    await rg.hasActiveReleaseRun(staleWaiting, 'o', 'r', noonUtc, fakeCore),
+    false
+  );
+  assert.ok(warnings.length === 1 && warnings[0].includes('approve or cancel'));
+
+  // …but an in_progress run always blocks regardless of age.
+  const oldInProgress = mockGithub({
+    runs: [{ status: 'in_progress', conclusion: null, created_at: '2026-07-07T01:00:00Z', html_url: 'x' }],
+  });
+  assert.strictEqual(
+    await rg.hasActiveReleaseRun(oldInProgress, 'o', 'r', noonUtc, null),
+    true
+  );

  console.log('ok: bumpPatch');
  console.log('ok: readVersionsFromTree');
+  console.log('ok: PACKAGE_PATHS covers all 9 released packages');
  console.log('ok: pypiVersionExists missing version');
  console.log('ok: utcDayStart');
-  console.log('ok: hasSuccessfulReleaseToday');
-  console.log('ok: daily dedupe blocks second release');
+  console.log('ok: release-based dedupe (recent blocks, old does not)');
+  console.log('ok: dry-run success does not consume the release window');
+  console.log('ok: 3-day dedupe blocks second release');
+  console.log('ok: fresh waiting run blocks; stale waiting run ignored with warning');
+  console.log('ok: in_progress always blocks');
 })();
@@ -4,10 +4,31 @@

 const https = require('https');

-const PACKAGE_PATHS = ['src/praisonai', 'src/praisonai-agents', 'src/praisonai-code'];
+/** Every directory whose changes should make a release eligible — all nine
+ * published packages (mirrors the skip_* inputs in pypi-release.yml). */
+const PACKAGE_PATHS = [
+  'src/praisonai',
+  'src/praisonai-agents',
+  'src/praisonai-code',
+  'src/praisonai-bot',
+  'src/praisonai-train',
+  'src/praisonai-browser',
+  'src/praisonai-mcp',
+  'src/praisonai-sandbox',
+  'src/praisonai-deploy',
+];
+/** Minimum days between successful patch auto-releases. */
+const PATCH_RELEASE_INTERVAL_DAYS = 3;
 const ACTIVE_RELEASE_STATUSES = new Set([
  'queued', 'in_progress', 'waiting', 'pending', 'requested',
 ]);
+/** A run stuck in `waiting` (environment approval) longer than this no longer
+ * blocks the gate. GitHub only auto-fails unapproved deployments after 30
+ * days, so without a cutoff one forgotten manual dispatch stalls all
+ * auto-releases for up to a month. The run is warned about, never cancelled —
+ * if later approved, the pypi-release concurrency group serializes it and its
+ * pypi_exists checks no-op anything already published. */
+const STALE_WAITING_HOURS = 6;

 function bumpPatch(version) {
  const parts = version.split('.');
@@ -63,36 +84,65 @@ function pypiVersionExists(packageName, version) {
  });
 }

-async function hasActiveReleaseRun(github, owner, repo) {
+async function hasActiveReleaseRun(github, owner, repo, now = new Date(), core = null) {
  const runs = await github.rest.actions.listWorkflowRuns({
    owner,
    repo,
    workflow_id: 'pypi-release.yml',
    per_page: 20,
  });
-  return runs.data.workflow_runs.some(
-    (r) => ACTIVE_RELEASE_STATUSES.has(r.status) && !r.conclusion
-  );
+  const staleCutoff = now.getTime() - STALE_WAITING_HOURS * 60 * 60 * 1000;
+  return runs.data.workflow_runs.some((r) => {
+    if (!ACTIVE_RELEASE_STATUSES.has(r.status) || r.conclusion) return false;
+    if (r.status === 'waiting' && new Date(r.created_at).getTime() < staleCutoff) {
+      if (core) {
+        core.warning(
+          `Ignoring release run waiting >${STALE_WAITING_HOURS}h for environment approval: `
+          + `${r.html_url} — approve or cancel it. It no longer blocks auto-releases.`
+        );
+      }
+      return false;
+    }
+    return true;
+  });
 }

 function utcDayStart(now = new Date()) {
  return new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), now.getUTCDate()));
 }

-async function hasSuccessfulReleaseToday(github, owner, repo, now = new Date()) {
-  const dayStart = utcDayStart(now);
-  const runs = await github.rest.actions.listWorkflowRuns({
+function releaseIntervalStart(now = new Date(), intervalDays = PATCH_RELEASE_INTERVAL_DAYS) {
+  return new Date(now.getTime() - intervalDays * 24 * 60 * 60 * 1000);
+}
+
+async function hasSuccessfulReleaseWithinDays(
+  github,
+  owner,
+  repo,
+  now = new Date(),
+  intervalDays = PATCH_RELEASE_INTERVAL_DAYS,
+) {
+  const windowStart = releaseIntervalStart(now, intervalDays);
+  // Dedupe on GitHub releases (v* tags) rather than run conclusions: a
+  // dry_run=true dispatch concludes 'success' without publishing anything and
+  // must not consume the release window. Only a real full release creates a
+  // v* GitHub release (bump_and_release.py's `gh release create`).
+  const releases = await github.rest.repos.listReleases({
    owner,
    repo,
-    workflow_id: 'pypi-release.yml',
-    status: 'completed',
-    per_page: 30,
+    per_page: 10,
  });
-  return runs.data.workflow_runs.some(
-    (r) => r.conclusion === 'success' && new Date(r.created_at) >= dayStart
+  return releases.data.some(
+    (r) => r.tag_name && r.tag_name.startsWith('v')
+      && new Date(r.published_at || r.created_at) >= windowStart
  );
 }

+/** @deprecated Use hasSuccessfulReleaseWithinDays — kept for selftests. */
+async function hasSuccessfulReleaseToday(github, owner, repo, now = new Date()) {
+  return hasSuccessfulReleaseWithinDays(github, owner, repo, now, 1);
+}
+
 async function lastGreenCoreTestsSha(github, owner, repo) {
  const runs = await github.rest.actions.listWorkflowRuns({
    owner,
@@ -129,15 +179,18 @@ async function evaluateReleasePreflight(github, owner, repo, options, core) {
    return out;
  }

-  if (await hasActiveReleaseRun(github, owner, repo)) {
+  const referenceTime = options.now instanceof Date ? options.now : new Date();
+
+  if (await hasActiveReleaseRun(github, owner, repo, referenceTime, core)) {
    reasons.push('PyPI Release already in progress or awaiting approval');
    return out;
  }

-  const referenceTime = options.now instanceof Date ? options.now : new Date();
-  if (await hasSuccessfulReleaseToday(github, owner, repo, referenceTime)) {
-    const day = referenceTime.toISOString().slice(0, 10);
-    reasons.push(`already released today (UTC ${day}); max one patch release per day`);
+  if (await hasSuccessfulReleaseWithinDays(github, owner, repo, referenceTime)) {
+    reasons.push(
+      `already released within last ${PATCH_RELEASE_INTERVAL_DAYS} days; `
+      + `max one patch release every ${PATCH_RELEASE_INTERVAL_DAYS} days`
+    );
    return out;
  }

@@ -207,8 +260,35 @@ async function evaluateReleasePreflight(github, owner, repo, options, core) {
    out.headSha = evalSha;
    const greenSha = await lastGreenCoreTestsSha(github, owner, repo);
    if (greenSha !== evalSha) {
-      reasons.push(`CI not green on HEAD (last green: ${greenSha ? greenSha.slice(0, 7) : 'none'})`);
-      return out;
+      // Core Tests has path filters and honors [skip ci] (the release
+      // safety-net commit uses it), so the tip of main may legitimately have
+      // no Core Tests run of its own — e.g. a docs-only commit, or the
+      // "chore(release): … [skip ci]" commit right after a release. Accept a
+      // green ancestor when nothing under the released package paths changed
+      // after it; otherwise the cron path stalls until the next src/** push.
+      let greenAncestorOk = false;
+      if (greenSha && /^[0-9a-f]{40}$/.test(greenSha)) {
+        try {
+          execSync(`git merge-base --is-ancestor ${greenSha} ${evalSha}`);
+          const delta = execSync(
+            `git diff --name-only ${greenSha} ${evalSha} -- ${PACKAGE_PATHS.join(' ')}`,
+            { encoding: 'utf8' }
+          ).trim();
+          greenAncestorOk = delta === '';
+        } catch {
+          greenAncestorOk = false;
+        }
+      }
+      if (!greenAncestorOk) {
+        reasons.push(`CI not green on HEAD (last green: ${greenSha ? greenSha.slice(0, 7) : 'none'})`);
+        return out;
+      }
+      if (core) {
+        core.info(
+          `HEAD ${evalSha.slice(0, 7)} has no Core Tests run; accepting green ancestor `
+          + `${greenSha.slice(0, 7)} (no package-path changes since).`
+        );
+      }
    }
  }

@@ -222,6 +302,11 @@ module.exports = {
  bumpPatch,
  readVersionsFromTree,
  pypiVersionExists,
+  PATCH_RELEASE_INTERVAL_DAYS,
+  STALE_WAITING_HOURS,
+  releaseIntervalStart,
+  hasActiveReleaseRun,
+  hasSuccessfulReleaseWithinDays,
  hasSuccessfulReleaseToday,
  utcDayStart,
  evaluateReleasePreflight,
@@ -1,12 +1,12 @@
 name: Nightly Release Gate

 # Preflight before PyPI Release (patch bump).
-# Triggers: Core Tests success on main (workflow_run) or nightly cron at 00:00 UTC.
-# Dedupe: max one successful patch release per UTC day (see release-gate.js).
+# Triggers: Core Tests success on main (workflow_run) or cron every 3 days at 00:00 UTC.
+# Dedupe: max one successful patch release every 3 days (see release-gate.js).

 on:
  schedule:
-    - cron: '0 0 * * *'
+    - cron: '0 0 */3 * *'
  workflow_dispatch:
    inputs:
      dry_run:
@@ -41,7 +41,7 @@ jobs:
        github.event.workflow_run.head_branch == 'main' &&
        github.event.workflow_run.event == 'push' &&
        !startsWith(github.event.workflow_run.head_commit.message, 'Release v') &&
-        !startsWith(github.event.workflow_run.head_commit.message, 'Bump praisonai')
+        !startsWith(github.event.workflow_run.head_commit.message, 'chore(release):')
      )
    runs-on: ubuntu-latest
    env:
@@ -69,6 +69,10 @@ jobs:
      - name: Fetch main and tags
        run: git fetch --tags origin main

+      # Guards the gate logic itself — no workflow ran these selftests before.
+      - name: Selftest release-gate script
+        run: node .github/scripts/release-gate-selftest.js
+
      - name: Preflight — path changes, CI SHA, dedupe
        id: preflight
        uses: actions/github-script@v7
@@ -61,6 +61,29 @@ on:
        required: false
        default: false
        type: boolean
+      skip_deploy:
+        description: 'Skip praisonai-deploy publish (recovery if already on PyPI)'
+        required: false
+        default: false
+        type: boolean
+      # NOTE: GitHub caps workflow_dispatch at 25 top-level inputs; this
+      # workflow has 23. Adding a 10th package (skip_* + *_version) hits 25.
+      only:
+        description: 'Release ONLY this package (forces skip on all others); all = no restriction'
+        required: false
+        default: all
+        type: choice
+        options:
+          - all
+          - agents
+          - code
+          - bot
+          - train
+          - browser
+          - mcp
+          - sandbox
+          - deploy
+          - wrapper
      agents_version:
        description: 'Override agents version (empty = auto bump from pyproject.toml)'
        required: false
@@ -101,6 +124,11 @@ on:
        required: false
        default: ''
        type: string
+      deploy_version:
+        description: 'Override praisonai-deploy version (empty = auto bump from pyproject.toml)'
+        required: false
+        default: ''
+        type: string
      source:
        description: 'Trigger source (audit trail)'
        required: false
@@ -134,15 +162,35 @@ jobs:
        'pypi-auto' || 'pypi'
      }}
    env:
-      UV_PUBLISH_TOKEN: ${{ secrets.PYPI_TOKEN || secrets.PYPI_API_TOKEN }}
-      GH_TOKEN: ${{ secrets.GH_TOKEN }}
+      # PyPI API token auth: username __token__, password = pypi-… token (see pypi.org/help/#invalid-auth)
+      UV_PUBLISH_USERNAME: __token__
+      UV_PUBLISH_PASSWORD: ${{ secrets.PYPI_TOKEN || secrets.PYPI_API_TOKEN }}
+      # GH_TOKEN is NOT set here: it is a GitHub App installation token minted in
+      # "Generate GitHub App token" and exported via $GITHUB_ENV, so releases are
+      # authored by praisonai-triage-agent[bot] rather than MervinPraison.
    steps:
+      - name: Generate GitHub App token
+        id: app-token
+        uses: actions/create-github-app-token@v1
+        with:
+          app-id: ${{ secrets.CLAUDE_APP_ID }}
+          private-key: ${{ secrets.CLAUDE_APP_PRIVATE_KEY }}
+          owner: ${{ github.repository_owner }}
+          # Scope to this repo only. Without it the token is minted for every
+          # repository the owner has; this job never leaves PraisonAI (checkout,
+          # push to origin, and gh release create all target it).
+          repositories: ${{ github.event.repository.name }}
+
      - name: Checkout main
        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5  # v4
        with:
          ref: main
          fetch-depth: 0
-          token: ${{ secrets.GH_TOKEN }}
+          token: ${{ steps.app-token.outputs.token }}
+          # Do not bake the token into .git/config: an http.extraheader would
+          # outrank the remote URL set in "Configure git" and pin this first
+          # (1h) token, defeating the refresh before the wrapper release.
+          persist-credentials: false

      - name: Set up Python
        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065  # v5
@@ -153,10 +201,19 @@ jobs:
        uses: astral-sh/setup-uv@38f3f104447c67c051c4a08e39b64a148898af3a  # v4

      - name: Configure git
+        env:
+          APP_TOKEN: ${{ steps.app-token.outputs.token }}
+          REPO: ${{ github.repository }}
        run: |
-          git config user.name "MervinPraison"
-          git config user.email "[email protected]"
-          gh auth setup-git
+          set -euo pipefail
+          git config user.name "praisonai-triage-agent[bot]"
+          git config user.email "272766704+praisonai-triage-agent[bot]@users.noreply.github.com"
+          # persist-credentials:false left the remote unauthenticated; push auth
+          # comes from the app token embedded here (masked in logs, and the
+          # token dies with the runner).
+          git remote set-url origin "https://x-access-token:${APP_TOKEN}@github.com/${REPO}.git"
+          echo "GH_TOKEN=${APP_TOKEN}" >> "$GITHUB_ENV"
+          GH_TOKEN="${APP_TOKEN}" gh auth setup-git

      - name: Release summary
        run: |
@@ -166,6 +223,36 @@ jobs:
          echo "Dry run: ${{ inputs.dry_run }}"
          echo "Environment: ${{ (inputs.source == 'ci' || inputs.source == 'nightly') && inputs.bump == 'patch' && 'pypi-auto' || 'pypi' }}"

+      # Single source of truth for which packages this run releases. `only`
+      # inverts into the skip flags here; everything downstream (version
+      # computation, PyPI detection, publish conditions) consumes these
+      # outputs, so a dedicated one-package release is one input instead of
+      # eight skip flags.
+      - name: Resolve effective skips
+        id: flags
+        env:
+          ONLY: ${{ inputs.only }}
+          SKIP_AGENTS: ${{ inputs.skip_agents }}
+          SKIP_CODE: ${{ inputs.skip_code }}
+          SKIP_BOT: ${{ inputs.skip_bot }}
+          SKIP_TRAIN: ${{ inputs.skip_train }}
+          SKIP_BROWSER: ${{ inputs.skip_browser }}
+          SKIP_MCP: ${{ inputs.skip_mcp }}
+          SKIP_SANDBOX: ${{ inputs.skip_sandbox }}
+          SKIP_DEPLOY: ${{ inputs.skip_deploy }}
+          SKIP_WRAPPER: ${{ inputs.skip_wrapper }}
+        run: |
+          set -euo pipefail
+          for pkg in agents code bot train browser mcp sandbox deploy wrapper; do
+            var="SKIP_$(echo "$pkg" | tr '[:lower:]' '[:upper:]')"
+            skip="${!var}"
+            if [ -n "${ONLY}" ] && [ "${ONLY}" != "all" ] && [ "${ONLY}" != "$pkg" ]; then
+              skip=true
+            fi
+            echo "skip_${pkg}=${skip}" >> "$GITHUB_OUTPUT"
+            echo "skip_${pkg}=${skip}"
+          done
+
      - name: Compute release versions
        id: versions
        env:
@@ -178,13 +265,15 @@ jobs:
          BROWSER_OVERRIDE: ${{ inputs.browser_version }}
          MCP_OVERRIDE: ${{ inputs.mcp_version }}
          SANDBOX_OVERRIDE: ${{ inputs.sandbox_version }}
-          SKIP_AGENTS: ${{ inputs.skip_agents }}
-          SKIP_CODE: ${{ inputs.skip_code }}
-          SKIP_BOT: ${{ inputs.skip_bot }}
-          SKIP_TRAIN: ${{ inputs.skip_train }}
-          SKIP_BROWSER: ${{ inputs.skip_browser }}
-          SKIP_MCP: ${{ inputs.skip_mcp }}
-          SKIP_SANDBOX: ${{ inputs.skip_sandbox }}
+          DEPLOY_OVERRIDE: ${{ inputs.deploy_version }}
+          SKIP_AGENTS: ${{ steps.flags.outputs.skip_agents }}
+          SKIP_CODE: ${{ steps.flags.outputs.skip_code }}
+          SKIP_BOT: ${{ steps.flags.outputs.skip_bot }}
+          SKIP_TRAIN: ${{ steps.flags.outputs.skip_train }}
+          SKIP_BROWSER: ${{ steps.flags.outputs.skip_browser }}
+          SKIP_MCP: ${{ steps.flags.outputs.skip_mcp }}
+          SKIP_SANDBOX: ${{ steps.flags.outputs.skip_sandbox }}
+          SKIP_DEPLOY: ${{ steps.flags.outputs.skip_deploy }}
        run: |
          python <<'PY'
          import os
@@ -221,6 +310,7 @@ jobs:
          browser_override = os.environ.get("BROWSER_OVERRIDE", "").strip()
          mcp_override = os.environ.get("MCP_OVERRIDE", "").strip()
          sandbox_override = os.environ.get("SANDBOX_OVERRIDE", "").strip()
+          deploy_override = os.environ.get("DEPLOY_OVERRIDE", "").strip()
          validate_version("agents_version", agents_override)
          validate_version("wrapper_version", wrapper_override)
          validate_version("code_version", code_override)
@@ -229,6 +319,7 @@ jobs:
          validate_version("browser_version", browser_override)
          validate_version("mcp_version", mcp_override)
          validate_version("sandbox_version", sandbox_override)
+          validate_version("deploy_version", deploy_override)

          agents_pyproject = root / "src/praisonai-agents/pyproject.toml"
          agents_content = agents_pyproject.read_text()
@@ -286,6 +377,14 @@ jobs:
              sys.exit(1)
          current_sandbox = sandbox_match.group(1)

+          deploy_pyproject = root / "src/praisonai-deploy/pyproject.toml"
+          deploy_content = deploy_pyproject.read_text()
+          deploy_match = re.search(r'^version\s*=\s*"([^"]+)"', deploy_content, re.MULTILINE)
+          if not deploy_match:
+              print("Could not read praisonai-deploy version from pyproject.toml", file=sys.stderr)
+              sys.exit(1)
+          current_deploy = deploy_match.group(1)
+
          wrapper_version_py = root / "src/praisonai/praisonai/version.py"
          wrapper_content = wrapper_version_py.read_text()
          wrapper_match = re.search(r'__version__ = "([^"]+)"', wrapper_content)
@@ -302,6 +401,7 @@ jobs:
              ("browser", current_browser),
              ("mcp", current_mcp),
              ("sandbox", current_sandbox),
+              ("deploy", current_deploy),
              ("wrapper", current_wrapper),
          ):
              if not SEMVER.match(value):
@@ -315,6 +415,7 @@ jobs:
          skip_browser = os.environ.get("SKIP_BROWSER", "false").lower() == "true"
          skip_mcp = os.environ.get("SKIP_MCP", "false").lower() == "true"
          skip_sandbox = os.environ.get("SKIP_SANDBOX", "false").lower() == "true"
+          skip_deploy = os.environ.get("SKIP_DEPLOY", "false").lower() == "true"

          if agents_override:
              agents_version = agents_override
@@ -365,6 +466,13 @@ jobs:
          else:
              sandbox_version = bump_version(current_sandbox)

+          if deploy_override:
+              deploy_version = deploy_override
+          elif skip_deploy:
+              deploy_version = current_deploy
+          else:
+              deploy_version = bump_version(current_deploy)
+
          if wrapper_override:
              wrapper_version = wrapper_override
          else:
@@ -379,6 +487,7 @@ jobs:
              fh.write(f"browser_version={browser_version}\n")
              fh.write(f"mcp_version={mcp_version}\n")
              fh.write(f"sandbox_version={sandbox_version}\n")
+              fh.write(f"deploy_version={deploy_version}\n")
              fh.write(f"wrapper_version={wrapper_version}\n")
              fh.write(f"current_agents={current_agents}\n")
              fh.write(f"current_code={current_code}\n")
@@ -387,6 +496,7 @@ jobs:
              fh.write(f"current_browser={current_browser}\n")
              fh.write(f"current_mcp={current_mcp}\n")
              fh.write(f"current_sandbox={current_sandbox}\n")
+              fh.write(f"current_deploy={current_deploy}\n")
              fh.write(f"current_wrapper={current_wrapper}\n")

          print(f"Agents:  {current_agents} -> {agents_version}")
@@ -396,6 +506,7 @@ jobs:
          print(f"Browser: {current_browser} -> {browser_version}")
          print(f"MCP:     {current_mcp} -> {mcp_version}")
          print(f"Sandbox: {current_sandbox} -> {sandbox_version}")
+          print(f"Deploy:  {current_deploy} -> {deploy_version}")
          print(f"Wrapper: {current_wrapper} -> {wrapper_version}")
          PY

@@ -410,15 +521,17 @@ jobs:
          BROWSER_VERSION: ${{ steps.versions.outputs.browser_version }}
          MCP_VERSION: ${{ steps.versions.outputs.mcp_version }}
          SANDBOX_VERSION: ${{ steps.versions.outputs.sandbox_version }}
+          DEPLOY_VERSION: ${{ steps.versions.outputs.deploy_version }}
          WRAPPER_VERSION: ${{ steps.versions.outputs.wrapper_version }}
-          INPUT_SKIP_AGENTS: ${{ inputs.skip_agents }}
-          INPUT_SKIP_CODE: ${{ inputs.skip_code }}
-          INPUT_SKIP_BOT: ${{ inputs.skip_bot }}
-          INPUT_SKIP_TRAIN: ${{ inputs.skip_train }}
-          INPUT_SKIP_BROWSER: ${{ inputs.skip_browser }}
-          INPUT_SKIP_MCP: ${{ inputs.skip_mcp }}
-          INPUT_SKIP_SANDBOX: ${{ inputs.skip_sandbox }}
-          INPUT_SKIP_WRAPPER: ${{ inputs.skip_wrapper }}
+          INPUT_SKIP_AGENTS: ${{ steps.flags.outputs.skip_agents }}
+          INPUT_SKIP_CODE: ${{ steps.flags.outputs.skip_code }}
+          INPUT_SKIP_BOT: ${{ steps.flags.outputs.skip_bot }}
+          INPUT_SKIP_TRAIN: ${{ steps.flags.outputs.skip_train }}
+          INPUT_SKIP_BROWSER: ${{ steps.flags.outputs.skip_browser }}
+          INPUT_SKIP_MCP: ${{ steps.flags.outputs.skip_mcp }}
+          INPUT_SKIP_SANDBOX: ${{ steps.flags.outputs.skip_sandbox }}
+          INPUT_SKIP_DEPLOY: ${{ steps.flags.outputs.skip_deploy }}
+          INPUT_SKIP_WRAPPER: ${{ steps.flags.outputs.skip_wrapper }}
        run: |
          set -euo pipefail
          skip_agents="${INPUT_SKIP_AGENTS}"
@@ -428,30 +541,53 @@ jobs:
          skip_browser="${INPUT_SKIP_BROWSER}"
          skip_mcp="${INPUT_SKIP_MCP}"
          skip_sandbox="${INPUT_SKIP_SANDBOX}"
+          skip_deploy="${INPUT_SKIP_DEPLOY}"
          skip_wrapper="${INPUT_SKIP_WRAPPER}"
+          # Returns 0 if published, 1 if definitively absent (404). Any other
+          # HTTP status (PyPI outage, 5xx, rate limit) FAILS the run: guessing
+          # "not published" would lead to a duplicate-upload failure midway
+          # through the release, which is strictly worse than stopping here
+          # before anything has been published.
+          pypi_published() { # $1=package $2=version
+            local code attempt
+            for attempt in 1 2 3; do
+              code=$(curl -s -o /dev/null -w '%{http_code}' --max-time 30 \
+                "https://pypi.org/pypi/$1/$2/json" || echo "000")
+              case "$code" in
+                200) return 0 ;;
+                404) return 1 ;;
+                *) echo "PyPI check $1==$2 returned HTTP ${code} (attempt ${attempt}/3)"; sleep 5 ;;
+              esac
+            done
+            echo "❌ Cannot determine PyPI state for $1==$2; refusing to guess." >&2
+            exit 2
+          }
          if [ "$skip_agents" != "true" ]; then
-            curl -fsSL "https://pypi.org/pypi/praisonaiagents/${AGENTS_VERSION}/json" >/dev/null && skip_agents=true || true
+            pypi_published praisonaiagents "${AGENTS_VERSION}" && skip_agents=true || true
          fi
          if [ "$skip_code" != "true" ]; then
-            curl -fsSL "https://pypi.org/pypi/praisonai-code/${CODE_VERSION}/json" >/dev/null && skip_code=true || true
+            pypi_published praisonai-code "${CODE_VERSION}" && skip_code=true || true
          fi
          if [ "$skip_bot" != "true" ]; then
-            curl -fsSL "https://pypi.org/pypi/praisonai-bot/${BOT_VERSION}/json" >/dev/null && skip_bot=true || true
+            pypi_published praisonai-bot "${BOT_VERSION}" && skip_bot=true || true
          fi
          if [ "$skip_train" != "true" ]; then
-            curl -fsSL "https://pypi.org/pypi/praisonai-train/${TRAIN_VERSION}/json" >/dev/null && skip_train=true || true
+            pypi_published praisonai-train "${TRAIN_VERSION}" && skip_train=true || true
          fi
          if [ "$skip_browser" != "true" ]; then
-            curl -fsSL "https://pypi.org/pypi/praisonai-browser/${BROWSER_VERSION}/json" >/dev/null && skip_browser=true || true
+            pypi_published praisonai-browser "${BROWSER_VERSION}" && skip_browser=true || true
          fi
          if [ "$skip_mcp" != "true" ]; then
-            curl -fsSL "https://pypi.org/pypi/praisonai-mcp/${MCP_VERSION}/json" >/dev/null && skip_mcp=true || true
+            pypi_published praisonai-mcp "${MCP_VERSION}" && skip_mcp=true || true
          fi
          if [ "$skip_sandbox" != "true" ]; then
-            curl -fsSL "https://pypi.org/pypi/praisonai-sandbox/${SANDBOX_VERSION}/json" >/dev/null && skip_sandbox=true || true
+            pypi_published praisonai-sandbox "${SANDBOX_VERSION}" && skip_sandbox=true || true
+          fi
+          if [ "$skip_deploy" != "true" ]; then
+            pypi_published praisonai-deploy "${DEPLOY_VERSION}" && skip_deploy=true || true
          fi
          if [ "$skip_wrapper" != "true" ]; then
-            curl -fsSL "https://pypi.org/pypi/praisonai/${WRAPPER_VERSION}/json" >/dev/null && skip_wrapper=true || true
+            pypi_published praisonai "${WRAPPER_VERSION}" && skip_wrapper=true || true
          fi
          echo "skip_agents=${skip_agents}" >> "$GITHUB_OUTPUT"
          echo "skip_code=${skip_code}" >> "$GITHUB_OUTPUT"
@@ -460,8 +596,9 @@ jobs:
          echo "skip_browser=${skip_browser}" >> "$GITHUB_OUTPUT"
          echo "skip_mcp=${skip_mcp}" >> "$GITHUB_OUTPUT"
          echo "skip_sandbox=${skip_sandbox}" >> "$GITHUB_OUTPUT"
+          echo "skip_deploy=${skip_deploy}" >> "$GITHUB_OUTPUT"
          echo "skip_wrapper=${skip_wrapper}" >> "$GITHUB_OUTPUT"
-          if [ "$skip_agents" = "true" ] && [ "$skip_code" = "true" ] && [ "$skip_bot" = "true" ] && [ "$skip_train" = "true" ] && [ "$skip_browser" = "true" ] && [ "$skip_mcp" = "true" ] && [ "$skip_sandbox" = "true" ] && [ "$skip_wrapper" = "true" ]; then
+          if [ "$skip_agents" = "true" ] && [ "$skip_code" = "true" ] && [ "$skip_bot" = "true" ] && [ "$skip_train" = "true" ] && [ "$skip_browser" = "true" ] && [ "$skip_mcp" = "true" ] && [ "$skip_sandbox" = "true" ] && [ "$skip_deploy" = "true" ] && [ "$skip_wrapper" = "true" ]; then
            echo "All target versions already on PyPI — nothing to publish."
          fi

@@ -475,6 +612,7 @@ jobs:
          steps.pypi_exists.outputs.skip_browser == 'true' &&
          steps.pypi_exists.outputs.skip_mcp == 'true' &&
          steps.pypi_exists.outputs.skip_sandbox == 'true' &&
+          steps.pypi_exists.outputs.skip_deploy == 'true' &&
          steps.pypi_exists.outputs.skip_wrapper == 'true'
        run: echo "Idempotent skip — target versions already on PyPI."

@@ -482,34 +620,43 @@ jobs:
        if: inputs.dry_run
        run: |
          echo "Dry run — no publish, commit, or push."
+          echo "Only:            ${{ inputs.only }}"
          echo "Agents version:  ${{ steps.versions.outputs.agents_version }}"
          echo "Code version:    ${{ steps.versions.outputs.code_version }}"
          echo "Bot version:     ${{ steps.versions.outputs.bot_version }}"
          echo "Train version:   ${{ steps.versions.outputs.train_version }}"
          echo "Browser version: ${{ steps.versions.outputs.browser_version }}"
          echo "MCP version:     ${{ steps.versions.outputs.mcp_version }}"
+          echo "Sandbox version: ${{ steps.versions.outputs.sandbox_version }}"
+          echo "Deploy version:  ${{ steps.versions.outputs.deploy_version }}"
          echo "Wrapper version: ${{ steps.versions.outputs.wrapper_version }}"
          echo ""
-          if [ "${{ inputs.skip_agents }}" != "true" ]; then
+          if [ "${{ steps.flags.outputs.skip_agents }}" != "true" ]; then
            echo "Would publish praisonaiagents ${{ steps.versions.outputs.agents_version }}"
          fi
-          if [ "${{ inputs.skip_code }}" != "true" ]; then
+          if [ "${{ steps.flags.outputs.skip_code }}" != "true" ]; then
            echo "Would publish praisonai-code ${{ steps.versions.outputs.code_version }}"
          fi
-          if [ "${{ inputs.skip_bot }}" != "true" ]; then
+          if [ "${{ steps.flags.outputs.skip_bot }}" != "true" ]; then
            echo "Would publish praisonai-bot ${{ steps.versions.outputs.bot_version }}"
          fi
-          if [ "${{ inputs.skip_train }}" != "true" ]; then
+          if [ "${{ steps.flags.outputs.skip_train }}" != "true" ]; then
            echo "Would publish praisonai-train ${{ steps.versions.outputs.train_version }}"
          fi
-          if [ "${{ inputs.skip_browser }}" != "true" ]; then
+          if [ "${{ steps.flags.outputs.skip_browser }}" != "true" ]; then
            echo "Would publish praisonai-browser ${{ steps.versions.outputs.browser_version }}"
          fi
-          if [ "${{ inputs.skip_mcp }}" != "true" ]; then
+          if [ "${{ steps.flags.outputs.skip_mcp }}" != "true" ]; then
            echo "Would publish praisonai-mcp ${{ steps.versions.outputs.mcp_version }}"
          fi
-          if [ "${{ inputs.skip_wrapper }}" != "true" ]; then
-            echo "Would run bump_and_release.py ${{ steps.versions.outputs.wrapper_version }} --agents ${{ steps.versions.outputs.agents_version }} --code-pin ${{ steps.versions.outputs.code_version }} --bot-pin ${{ steps.versions.outputs.bot_version }} --train-pin ${{ steps.versions.outputs.train_version }} --browser-pin ${{ steps.versions.outputs.browser_version }} --mcp-pin ${{ steps.versions.outputs.mcp_version }}"
+          if [ "${{ steps.flags.outputs.skip_sandbox }}" != "true" ]; then
+            echo "Would publish praisonai-sandbox ${{ steps.versions.outputs.sandbox_version }}"
+          fi
+          if [ "${{ steps.flags.outputs.skip_deploy }}" != "true" ]; then
+            echo "Would publish praisonai-deploy ${{ steps.versions.outputs.deploy_version }}"
+          fi
+          if [ "${{ steps.flags.outputs.skip_wrapper }}" != "true" ]; then
+            echo "Would run bump_and_release.py ${{ steps.versions.outputs.wrapper_version }} --agents ${{ steps.versions.outputs.agents_version }} --code-pin ${{ steps.versions.outputs.code_version }} --bot-pin ${{ steps.versions.outputs.bot_version }} --train-pin ${{ steps.versions.outputs.train_version }} --browser-pin ${{ steps.versions.outputs.browser_version }} --mcp-pin ${{ steps.versions.outputs.mcp_version }} --sandbox-pin ${{ steps.versions.outputs.sandbox_version }} --deploy-pin ${{ steps.versions.outputs.deploy_version }}"
            echo "Would uv publish praisonai ${{ steps.versions.outputs.wrapper_version }}"
          fi

@@ -537,7 +684,9 @@ jobs:
          rm -rf dist
          uv lock
          uv build
-          uv publish
+          # --check-url makes re-uploads idempotent: files already on PyPI are
+          # skipped instead of failing the publish (partial-upload recovery).
+          uv publish --check-url https://pypi.org/simple/

      - name: Wait for praisonaiagents on PyPI
        if: >-
@@ -566,19 +715,6 @@ jobs:
            sleep "$INTERVAL"
          done

-      - name: Commit agents version bump
-        if: >-
-          inputs.dry_run != true &&
-          inputs.skip_agents != true &&
-          steps.pypi_exists.outputs.skip_agents != 'true'
-        run: |
-          set -euo pipefail
-          git add src/praisonai-agents/pyproject.toml src/praisonai-agents/uv.lock
-          git diff --cached --quiet && { echo "No agents files to commit"; exit 0; }
-          git commit -m "Bump praisonaiagents to ${{ steps.versions.outputs.agents_version }}"
-          git pull --rebase origin main
-          git push origin main
-
      - name: Publish praisonai-code
        if: >-
          inputs.dry_run != true &&
@@ -607,7 +743,9 @@ jobs:
          rm -rf dist
          uv lock
          uv build
-          uv publish
+          # --check-url makes re-uploads idempotent: files already on PyPI are
+          # skipped instead of failing the publish (partial-upload recovery).
+          uv publish --check-url https://pypi.org/simple/

      - name: Wait for praisonai-code on PyPI
        if: >-
@@ -636,19 +774,6 @@ jobs:
            sleep "$INTERVAL"
          done

-      - name: Commit praisonai-code version bump
-        if: >-
-          inputs.dry_run != true &&
-          inputs.skip_code != true &&
-          steps.pypi_exists.outputs.skip_code != 'true'
-        run: |
-          set -euo pipefail
-          git add src/praisonai-code/pyproject.toml src/praisonai-code/uv.lock src/praisonai-code/praisonai_code/__init__.py
-          git diff --cached --quiet && { echo "No code files to commit"; exit 0; }
-          git commit -m "Bump praisonai-code to ${{ steps.versions.outputs.code_version }}"
-          git pull --rebase origin main
-          git push origin main
-
      - name: Publish praisonai-bot
        if: >-
          inputs.dry_run != true &&
@@ -677,7 +802,9 @@ jobs:
          rm -rf dist
          uv lock
          uv build
-          uv publish
+          # --check-url makes re-uploads idempotent: files already on PyPI are
+          # skipped instead of failing the publish (partial-upload recovery).
+          uv publish --check-url https://pypi.org/simple/

      - name: Wait for praisonai-bot on PyPI
        if: >-
@@ -706,19 +833,6 @@ jobs:
            sleep "$INTERVAL"
          done

-      - name: Commit praisonai-bot version bump
-        if: >-
-          inputs.dry_run != true &&
-          inputs.skip_bot != true &&
-          steps.pypi_exists.outputs.skip_bot != 'true'
-        run: |
-          set -euo pipefail
-          git add src/praisonai-bot/pyproject.toml src/praisonai-bot/uv.lock src/praisonai-bot/praisonai_bot/_version.py
-          git diff --cached --quiet && { echo "No bot files to commit"; exit 0; }
-          git commit -m "Bump praisonai-bot to ${{ steps.versions.outputs.bot_version }}"
-          git pull --rebase origin main
-          git push origin main
-
      - name: Publish praisonai-train
        if: >-
          inputs.dry_run != true &&
@@ -747,7 +861,9 @@ jobs:
          rm -rf dist
          uv lock
          uv build
-          uv publish
+          # --check-url makes re-uploads idempotent: files already on PyPI are
+          # skipped instead of failing the publish (partial-upload recovery).
+          uv publish --check-url https://pypi.org/simple/

      - name: Wait for praisonai-train on PyPI
        if: >-
@@ -776,19 +892,6 @@ jobs:
            sleep "$INTERVAL"
          done

-      - name: Commit praisonai-train version bump
-        if: >-
-          inputs.dry_run != true &&
-          inputs.skip_train != true &&
-          steps.pypi_exists.outputs.skip_train != 'true'
-        run: |
-          set -euo pipefail
-          git add src/praisonai-train/pyproject.toml src/praisonai-train/uv.lock src/praisonai-train/praisonai_train/_version.py
-          git diff --cached --quiet && { echo "No train files to commit"; exit 0; }
-          git commit -m "Bump praisonai-train to ${{ steps.versions.outputs.train_version }}"
-          git pull --rebase origin main
-          git push origin main
-
      - name: Publish praisonai-browser
        if: >-
          inputs.dry_run != true &&
@@ -817,7 +920,9 @@ jobs:
          rm -rf dist
          uv lock
          uv build
-          uv publish
+          # --check-url makes re-uploads idempotent: files already on PyPI are
+          # skipped instead of failing the publish (partial-upload recovery).
+          uv publish --check-url https://pypi.org/simple/

      - name: Wait for praisonai-browser on PyPI
        if: >-
@@ -846,19 +951,6 @@ jobs:
            sleep "$INTERVAL"
          done

-      - name: Commit praisonai-browser version bump
-        if: >-
-          inputs.dry_run != true &&
-          inputs.skip_browser != true &&
-          steps.pypi_exists.outputs.skip_browser != 'true'
-        run: |
-          set -euo pipefail
-          git add src/praisonai-browser/pyproject.toml src/praisonai-browser/uv.lock src/praisonai-browser/praisonai_browser/_version.py
-          git diff --cached --quiet && { echo "No browser files to commit"; exit 0; }
-          git commit -m "Bump praisonai-browser to ${{ steps.versions.outputs.browser_version }}"
-          git pull --rebase origin main
-          git push origin main
-
      - name: Publish praisonai-mcp
        if: >-
          inputs.dry_run != true &&
@@ -887,7 +979,9 @@ jobs:
          rm -rf dist
          uv lock
          uv build
-          uv publish
+          # --check-url makes re-uploads idempotent: files already on PyPI are
+          # skipped instead of failing the publish (partial-upload recovery).
+          uv publish --check-url https://pypi.org/simple/

      - name: Wait for praisonai-mcp on PyPI
        if: >-
@@ -916,19 +1010,6 @@ jobs:
            sleep "$INTERVAL"
          done

-      - name: Commit praisonai-mcp version bump
-        if: >-
-          inputs.dry_run != true &&
-          inputs.skip_mcp != true &&
-          steps.pypi_exists.outputs.skip_mcp != 'true'
-        run: |
-          set -euo pipefail
-          git add src/praisonai-mcp/pyproject.toml src/praisonai-mcp/uv.lock src/praisonai-mcp/praisonai_mcp/_version.py
-          git diff --cached --quiet && { echo "No mcp files to commit"; exit 0; }
-          git commit -m "Bump praisonai-mcp to ${{ steps.versions.outputs.mcp_version }}"
-          git pull --rebase origin main
-          git push origin main
-
      - name: Publish praisonai-sandbox
        if: >-
          inputs.dry_run != true &&
@@ -957,7 +1038,9 @@ jobs:
          rm -rf dist
          uv lock
          uv build
-          uv publish
+          # --check-url makes re-uploads idempotent: files already on PyPI are
+          # skipped instead of failing the publish (partial-upload recovery).
+          uv publish --check-url https://pypi.org/simple/

      - name: Wait for praisonai-sandbox on PyPI
        if: >-
@@ -986,20 +1069,101 @@ jobs:
            sleep "$INTERVAL"
          done

-      - name: Commit praisonai-sandbox version bump
+      - name: Publish praisonai-deploy
        if: >-
          inputs.dry_run != true &&
-          inputs.skip_sandbox != true &&
-          steps.pypi_exists.outputs.skip_sandbox != 'true'
+          inputs.skip_deploy != true &&
+          steps.pypi_exists.outputs.skip_deploy != 'true'
+        working-directory: src/praisonai-deploy
+        env:
+          NEW_VERSION: ${{ steps.versions.outputs.deploy_version }}
+          CURRENT: ${{ steps.versions.outputs.current_deploy }}
        run: |
          set -euo pipefail
-          git add src/praisonai-sandbox/pyproject.toml src/praisonai-sandbox/uv.lock src/praisonai-sandbox/praisonai_sandbox/_version.py
-          git diff --cached --quiet && { echo "No sandbox files to commit"; exit 0; }
-          git commit -m "Bump praisonai-sandbox to ${{ steps.versions.outputs.sandbox_version }}"
-          git pull --rebase origin main
-          git push origin main
+          python <<'PY'
+          import os
+          import re
+          from pathlib import Path
+          new = os.environ["NEW_VERSION"]
+          current = os.environ["CURRENT"]
+          pyproject = Path("pyproject.toml")
+          content = pyproject.read_text()
+          pyproject.write_text(content.replace(f'version = "{current}"', f'version = "{new}"', 1))
+          version_py = Path("praisonai_deploy/_version.py")
+          version_content = version_py.read_text()
+          version_py.write_text(re.sub(r'__version__ = "[^"]+"', f'__version__ = "{new}"', version_content, count=1))
+          PY
+
+          rm -rf dist
+          uv lock
+          uv build
+          # --check-url makes re-uploads idempotent: files already on PyPI are
+          # skipped instead of failing the publish (partial-upload recovery).
+          uv publish --check-url https://pypi.org/simple/
+
+      - name: Wait for praisonai-deploy on PyPI
+        if: >-
+          inputs.dry_run != true &&
+          inputs.skip_deploy != true &&
+          steps.pypi_exists.outputs.skip_deploy != 'true'
+        run: |
+          set -euo pipefail
+          PACKAGE="praisonai-deploy"
+          VERSION="${{ steps.versions.outputs.deploy_version }}"
+          MAX_WAIT=600
+          INTERVAL=30
+          START=$(date +%s)
+
+          while true; do
+            if curl -fsSL "https://pypi.org/pypi/${PACKAGE}/${VERSION}/json" >/dev/null; then
+              echo "✅ ${PACKAGE}==${VERSION} is available on PyPI"
+              exit 0
+            fi
+            ELAPSED=$(( $(date +%s) - START ))
+            if [ "$ELAPSED" -ge "$MAX_WAIT" ]; then
+              echo "❌ Timeout waiting for ${PACKAGE}==${VERSION} on PyPI"
+              exit 1
+            fi
+            echo "⏳ Waiting for ${PACKAGE}==${VERSION} ($(( MAX_WAIT - ELAPSED ))s remaining...)"
+            sleep "$INTERVAL"
+          done
+
+      # All per-package version bumps are still uncommitted at this point: the
+      # wrapper release below stages every one of them (bump_and_release.py's
+      # release_files list) into a SINGLE "Release v…" commit.
+
+      # App tokens expire after 1h and this job can exceed that (9 packages ×
+      # up to a 600s PyPI wait). Re-mint so the final commit/tag/push/release
+      # never runs on an expired token.
+      - name: Refresh GitHub App token
+        id: app-token-final
+        if: ${{ !cancelled() && inputs.dry_run != true }}
+        # A failed re-mint must not fail the release: the original token may
+        # still be valid, and the next step only swaps tokens on success.
+        continue-on-error: true
+        uses: actions/create-github-app-token@v1
+        with:
+          app-id: ${{ secrets.CLAUDE_APP_ID }}
+          private-key: ${{ secrets.CLAUDE_APP_PRIVATE_KEY }}
+          owner: ${{ github.repository_owner }}
+          repositories: ${{ github.event.repository.name }}
+
+      # Guarded on the refresh actually succeeding: if the re-mint failed
+      # (API blip), the ORIGINAL token — still wired into the remote URL and
+      # GH_TOKEN — may well be valid, and overwriting it with an empty string
+      # would turn a recoverable situation into a guaranteed auth failure.
+      - name: Use refreshed GitHub App token
+        if: ${{ !cancelled() && inputs.dry_run != true && steps.app-token-final.outcome == 'success' }}
+        env:
+          APP_TOKEN: ${{ steps.app-token-final.outputs.token }}
+          REPO: ${{ github.repository }}
+        run: |
+          set -euo pipefail
+          git remote set-url origin "https://x-access-token:${APP_TOKEN}@github.com/${REPO}.git"
+          echo "GH_TOKEN=${APP_TOKEN}" >> "$GITHUB_ENV"

      - name: Bump and release wrapper
+        id: wrapper
        if: >-
          inputs.dry_run != true &&
          inputs.skip_wrapper != true &&
@@ -1014,7 +1178,8 @@ jobs:
            --browser-pin "${{ steps.versions.outputs.browser_version }}" \
            --mcp-pin "${{ steps.versions.outputs.mcp_version }}" \
            --sandbox-pin "${{ steps.versions.outputs.sandbox_version }}" \
-            --wait --max-wait 600 --no-add-all
+            --deploy-pin "${{ steps.versions.outputs.deploy_version }}" \
+            --wait --max-wait 600 --no-add-all --force

      - name: Publish praisonai wrapper to PyPI
        if: >-
@@ -1022,7 +1187,7 @@ jobs:
          inputs.skip_wrapper != true &&
          steps.pypi_exists.outputs.skip_wrapper != 'true'
        working-directory: src/praisonai
-        run: uv publish
+        run: uv publish --check-url https://pypi.org/simple/

      - name: Wait for praisonai on PyPI
        if: >-
@@ -1051,47 +1216,139 @@ jobs:
            sleep "$INTERVAL"
          done

+      # Actually probes PyPI — previously this step only echoed checkmarks
+      # from the input flags, so it "verified" publishes that never happened.
      - name: Verify PyPI versions
        if: inputs.dry_run != true
        run: |
          set -euo pipefail
-          AGENTS="${{ steps.versions.outputs.agents_version }}"
-          CODE="${{ steps.versions.outputs.code_version }}"
-          BOT="${{ steps.versions.outputs.bot_version }}"
-          TRAIN="${{ steps.versions.outputs.train_version }}"
-          BROWSER="${{ steps.versions.outputs.browser_version }}"
-          MCP="${{ steps.versions.outputs.mcp_version }}"
-          SANDBOX="${{ steps.versions.outputs.sandbox_version }}"
-          WRAPPER="${{ steps.versions.outputs.wrapper_version }}"
+          verify() { # $1=pypi-name $2=version $3=effective-skip
+            if [ "$3" = "true" ]; then
+              echo "⏭️  $1 skipped"
+              return 0
+            fi
+            if curl -fsSL --max-time 30 "https://pypi.org/pypi/$1/$2/json" >/dev/null; then
+              echo "✅ $1==$2"
+            else
+              echo "❌ $1==$2 NOT found on PyPI"
+              exit 1
+            fi
+          }
+          verify praisonaiagents  "${{ steps.versions.outputs.agents_version }}"  "${{ steps.flags.outputs.skip_agents }}"
+          verify praisonai-code   "${{ steps.versions.outputs.code_version }}"    "${{ steps.flags.outputs.skip_code }}"
+          verify praisonai-bot    "${{ steps.versions.outputs.bot_version }}"     "${{ steps.flags.outputs.skip_bot }}"
+          verify praisonai-train  "${{ steps.versions.outputs.train_version }}"   "${{ steps.flags.outputs.skip_train }}"
+          verify praisonai-browser "${{ steps.versions.outputs.browser_version }}" "${{ steps.flags.outputs.skip_browser }}"
+          verify praisonai-mcp    "${{ steps.versions.outputs.mcp_version }}"     "${{ steps.flags.outputs.skip_mcp }}"
+          verify praisonai-sandbox "${{ steps.versions.outputs.sandbox_version }}" "${{ steps.flags.outputs.skip_sandbox }}"
+          verify praisonai-deploy "${{ steps.versions.outputs.deploy_version }}"  "${{ steps.flags.outputs.skip_deploy }}"
+          verify praisonai        "${{ steps.versions.outputs.wrapper_version }}" "${{ steps.flags.outputs.skip_wrapper }}"

-          if [ "${{ inputs.skip_agents }}" != "true" ]; then
-            echo "✅ praisonaiagents==${AGENTS}"
+      # Safety net. On a clean run the wrapper's "Release v…" commit already
+      # carries every bump and this is a no-op. It only fires when the single
+      # commit could not happen: a package publish failed midway (those versions
+      # are already live on PyPI, so the bumps must not be lost), skip_wrapper
+      # was set, or the wrapper itself failed.
+      - name: Persist any uncommitted version bumps
+        if: ${{ !cancelled() && inputs.dry_run != true }}
+        run: |
+          set -euo pipefail
+          # If the wrapper release did not complete, drop any uncommitted
+          # wrapper-side rewrites (version.py, Dockerfiles, pins): committing
+          # them would put a wrapper version on main that never reached PyPI,
+          # and the next auto-bump would skip past it forever. Committed
+          # changes are untouched (checkout only reverts the working tree),
+          # and if the wrapper was skipped these files were never modified.
+          if [ "${{ steps.wrapper.outcome }}" != "success" ]; then
+            git checkout -- \
+              src/praisonai/praisonai/version.py \
+              src/praisonai/pyproject.toml \
+              src/praisonai/uv.lock \
+              src/praisonai/README.md \
+              src/praisonai/praisonai.rb \
+              src/praisonai-deploy/praisonai_deploy/docker.py \
+              docker/ 2>/dev/null || true
          fi
+          # -u = tracked modifications only; uv build output under dist/ is
+          # untracked and stays out of the commit.
+          git add -u
+          git diff --cached --quiet && { echo "Nothing left to commit"; exit 0; }
+          # Name the packages actually staged, so a single-package release
+          # (every other skip_* set) reads "bump praisonai-mcp" rather than a
+          # generic message. Falls back when nothing under src/ is staged.
+          PKGS="$(git diff --cached --name-only \
+            | sed -n 's#^src/\([^/]*\)/.*#\1#p' | sort -u | tr '\n' ' ' | sed 's/ *$//')"
+          if [ -n "$PKGS" ]; then
+            MSG="chore(release): bump ${PKGS} [skip ci]"
+          else
+            MSG="chore(release): persist version bumps [skip ci]"
+          fi
+          echo "Commit message: ${MSG}"
+          git commit -m "$MSG"
+          # This step fires exactly when the release went sideways — i.e. when
+          # main is most likely to have moved — so the rebase+push retries.
+          # Losing this commit deadlocks future auto-releases: the packages
+          # are on PyPI at N+1 while the repo says N, so every later run
+          # detects "already published" and skips both publish and bump.
+          for attempt in 1 2 3; do
+            git fetch origin main
+            if ! git rebase origin/main; then
+              git rebase --abort || true
+              # During rebase, "theirs" is the commit being replayed — the
+              # version bumps — so they win any conflict.
+              if ! git rebase -X theirs origin/main; then
+                git rebase --abort || true
+                echo "Rebase attempt ${attempt}/3 failed"
+                sleep 5
+                continue
+              fi
+            fi
+            if git push origin main; then
+              echo "Pushed version bumps (attempt ${attempt}/3)"
+              exit 0
+            fi
+            echo "Push attempt ${attempt}/3 rejected; retrying..."
+            sleep 5
+          done
+          echo "❌ Could not push version bumps after 3 attempts."
+          echo "   Repo is now BEHIND PyPI; commit the version files on main manually"
+          echo "   or future auto-releases will no-op ('already published')."
+          exit 1

-          if [ "${{ inputs.skip_code }}" != "true" ]; then
-            echo "✅ praisonai-code==${CODE}"
-          fi
-
-          if [ "${{ inputs.skip_bot }}" != "true" ]; then
-            echo "✅ praisonai-bot==${BOT}"
-          fi
-
-          if [ "${{ inputs.skip_train }}" != "true" ]; then
-            echo "✅ praisonai-train==${TRAIN}"
-          fi
-
-          if [ "${{ inputs.skip_browser }}" != "true" ]; then
-            echo "✅ praisonai-browser==${BROWSER}"
-          fi
-
-          if [ "${{ inputs.skip_mcp }}" != "true" ]; then
-            echo "✅ praisonai-mcp==${MCP}"
-          fi
-
-          if [ "${{ inputs.skip_sandbox }}" != "true" ]; then
-            echo "✅ praisonai-sandbox==${SANDBOX}"
-          fi
-
-          if [ "${{ inputs.skip_wrapper }}" != "true" ]; then
-            echo "✅ praisonai==${WRAPPER}"
-          fi
+      # Dedicated releases (skip_wrapper) create no "Release v…" tag — the
+      # wrapper drives that — so tag each published package individually for
+      # provenance. Full releases keep their single v… tag unchanged.
+      - name: Tag dedicated package releases
+        if: >-
+          ${{ !cancelled() && inputs.dry_run != true &&
+              steps.flags.outputs.skip_wrapper == 'true' &&
+              steps.versions.outcome == 'success' }}
+        run: |
+          set -euo pipefail
+          tag_pkg() { # $1=effective-skip $2=pypi-name $3=version
+            if [ "$1" = "true" ]; then
+              return 0
+            fi
+            local tag="$2-v$3"
+            # Only tag what is confirmed on PyPI — a package whose publish
+            # failed must not get a tag claiming it shipped.
+            if ! curl -fsSL --max-time 30 "https://pypi.org/pypi/$2/$3/json" >/dev/null; then
+              echo "⏭️  $2==$3 not on PyPI; not tagging"
+              return 0
+            fi
+            if git rev-parse -q --verify "refs/tags/${tag}" >/dev/null; then
+              echo "tag ${tag} already exists"
+              return 0
+            fi
+            git tag "${tag}"
+            git push origin "refs/tags/${tag}"
+            echo "🏷️  ${tag}"
+          }
+          tag_pkg "${{ steps.flags.outputs.skip_agents }}"  praisonaiagents  "${{ steps.versions.outputs.agents_version }}"
+          tag_pkg "${{ steps.flags.outputs.skip_code }}"    praisonai-code   "${{ steps.versions.outputs.code_version }}"
+          tag_pkg "${{ steps.flags.outputs.skip_bot }}"     praisonai-bot    "${{ steps.versions.outputs.bot_version }}"
+          tag_pkg "${{ steps.flags.outputs.skip_train }}"   praisonai-train  "${{ steps.versions.outputs.train_version }}"
+          tag_pkg "${{ steps.flags.outputs.skip_browser }}" praisonai-browser "${{ steps.versions.outputs.browser_version }}"
+          tag_pkg "${{ steps.flags.outputs.skip_mcp }}"     praisonai-mcp    "${{ steps.versions.outputs.mcp_version }}"
+          tag_pkg "${{ steps.flags.outputs.skip_sandbox }}" praisonai-sandbox "${{ steps.versions.outputs.sandbox_version }}"
+          tag_pkg "${{ steps.flags.outputs.skip_deploy }}"  praisonai-deploy "${{ steps.versions.outputs.deploy_version }}"
@@ -5,6 +5,9 @@ on:
    branches: [ main, develop ]
    paths:
      - 'src/**'
+      - 'src/praisonai-deploy/infra/**'
+      - 'src/praisonai-bot/infra/**'
+      - 'scripts/check_helm_charts.sh'
      - 'pyproject.toml'
      - '.github/workflows/test-core.yml'
      - '.github/actions/install-monorepo-packages/**'
@@ -12,6 +15,9 @@ on:
    branches: [ main, develop ]
    paths:
      - 'src/**'
+      - 'src/praisonai-deploy/infra/**'
+      - 'src/praisonai-bot/infra/**'
+      - 'scripts/check_helm_charts.sh'
      - 'pyproject.toml'
      - '.github/workflows/test-core.yml'
      - '.github/actions/install-monorepo-packages/**'
@@ -114,11 +120,17 @@ jobs:
            extra_ignore: ""
            pythonpath: >-
              ${{ github.workspace }}/src/praisonai-agents
+          - shard: deploy
+            workdir: src/praisonai-deploy
+            paths: >-
+              tests/
+            extra_ignore: ""
+            pythonpath: >-
+              ${{ github.workspace }}/src/praisonai-agents
          - shard: subdirs
            paths: >-
              tests/unit/scheduler/
              tests/unit/integrations/
-              tests/unit/deploy/
              tests/unit/mcp/
              tests/unit/knowledge/
              tests/unit/llm/
@@ -183,6 +195,9 @@ jobs:
        if [ "$WORKDIR" = "src/praisonai-sandbox" ]; then
          bash "$GITHUB_WORKSPACE/scripts/check_c13_sandbox_imports.sh"
        fi
+        if [ "$WORKDIR" = "src/praisonai-deploy" ]; then
+          bash "$GITHUB_WORKSPACE/scripts/check_c14_deploy_imports.sh"
+        fi
        if [ "$WORKDIR" = "src/praisonai-mcp" ]; then
          bash "$GITHUB_WORKSPACE/scripts/check_c12_mcp_imports.sh"
        fi
@@ -268,9 +283,27 @@ jobs:
          --ignore=tests/integration/test_tracker_complex_tasks.py \
          --ignore=tests/integration/test_serve_integration.py

+  helm-charts:
+    name: helm-charts
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+    - uses: actions/checkout@v4
+      with:
+        persist-credentials: false
+    - name: Setup Helm
+      uses: azure/setup-helm@v3
+      with:
+        version: v3.14.4
+    - name: Lint and template Helm charts
+      shell: bash
+      run: |
+        set -euo pipefail
+        bash "$GITHUB_WORKSPACE/scripts/check_helm_charts.sh"
+
  test-core:
    name: test-core
-    needs: [test-core-collect, test-core-unit, test-core-integration]
+    needs: [test-core-collect, test-core-unit, test-core-integration, helm-charts]
    if: always()
    runs-on: ubuntu-latest
    timeout-minutes: 5
@@ -282,8 +315,9 @@ jobs:
        collect='${{ needs.test-core-collect.result }}'
        unit='${{ needs.test-core-unit.result }}'
        integration='${{ needs.test-core-integration.result }}'
-        echo "collect=$collect unit=$unit integration=$integration"
-        if [ "$collect" != "success" ] || [ "$unit" != "success" ] || [ "$integration" != "success" ]; then
+        helm='${{ needs.helm-charts.result }}'
+        echo "collect=$collect unit=$unit integration=$integration helm=$helm"
+        if [ "$collect" != "success" ] || [ "$unit" != "success" ] || [ "$integration" != "success" ] || [ "$helm" != "success" ]; then
          echo "Core Tests failed"
          exit 1
        fi
@@ -86,6 +86,7 @@ jobs:
          tests/unit/test_c11_browser_backward_compat.py \
          tests/unit/test_c12_mcp_backward_compat.py \
          tests/unit/test_c13_sandbox_backward_compat.py \
+          tests/unit/test_c14_deploy_backward_compat.py \
          -q --tb=line --timeout=30 --maxfail=5
        python -m pytest tests/unit/cli/ \
          ../praisonai-bot/tests/unit/cli/test_onboard_command.py \
@@ -269,10 +270,26 @@ jobs:
        bash "$GITHUB_WORKSPACE/scripts/check_c13_sandbox_imports.sh"
        python -m pytest src/praisonai-sandbox/tests -q -m "not network"

+    - name: Standalone praisonai-deploy smoke (C14)
+      run: |
+        set -euo pipefail
+        python -m venv /tmp/praisonai-deploy-standalone
+        /tmp/praisonai-deploy-standalone/bin/pip install -q -e src/praisonai-agents -e src/praisonai-deploy
+        /tmp/praisonai-deploy-standalone/bin/python -c "
+        from praisonai_deploy._version import __version__ as pkg_version
+        import praisonai_deploy
+        assert praisonai_deploy.__version__ == pkg_version
+        assert 'main' not in __import__('sys').modules
+        print('deploy standalone ok', praisonai_deploy.__version__)
+        "
+        /tmp/praisonai-deploy-standalone/bin/praisonai-deploy --help
+        bash "$GITHUB_WORKSPACE/scripts/check_c14_deploy_imports.sh"
+        python -m pytest src/praisonai-deploy/tests -q -m "not network"
+
    - name: Audit hybrid module imports (C8 full stack)
      run: |
        set -euo pipefail
-        pip install -q -e src/praisonai-agents -e src/praisonai-code -e src/praisonai-bot -e src/praisonai-train -e src/praisonai-browser -e src/praisonai-mcp -e src/praisonai-sandbox -e src/praisonai
+        pip install -q -e src/praisonai-agents -e src/praisonai-code -e src/praisonai-bot -e src/praisonai-train -e src/praisonai-browser -e src/praisonai-mcp -e src/praisonai-sandbox -e src/praisonai-deploy -e src/praisonai
        python scripts/audit_hybrid_modules.py
    
    - name: Smoke Test Summary
@@ -782,6 +799,9 @@ jobs:
          tests/unit/test_decorator_simple.py
          tests/unit/test_db_adapter_tracing_init.py
          ../praisonai-bot/tests/unit/test_bot_wiring.py
+          ../praisonai-bot/tests/unit/bots/test_enable_shell.py
+          ../praisonai-bot/tests/unit/gateway/test_preflight.py
+          ../praisonai-bot/tests/unit/gateway/test_gateway_doctor.py
          ../praisonai-bot/tests/unit/test_bot_history.py
          ../praisonai-bot/tests/unit/test_bot_fixes.py
          tests/unit/test_auto_lazy_loading.py
@@ -7,9 +7,9 @@ You are working on the PraisonAI project.
 - Be concise and helpful in responses  
 - Test implementation thoroughly
 - Ensure backward compatibility with existing APIs
- Follow protocol-driven design across the eight packages: core protocols in `praisonaiagents/`, agentic terminal CLI in `praisonai-code/`, bots/gateway in `praisonai-bot/`, LLM fine-tuning + agent training in `praisonai-train/`, browser automation in `praisonai-browser/`, MCP server host in `praisonai-mcp/`, sandbox backends in `praisonai-sandbox/`, integrations/serve/dashboard in the `praisonai/` wrapper
+- Follow protocol-driven design across the nine packages: core protocols in `praisonaiagents/`, agentic terminal CLI in `praisonai-code/`, bots/gateway in `praisonai-bot/`, LLM fine-tuning + agent training in `praisonai-train/`, browser automation in `praisonai-browser/`, MCP server host in `praisonai-mcp/`, sandbox backends in `praisonai-sandbox/`, deployment in `praisonai-deploy/`, integrations/serve/dashboard in the `praisonai/` wrapper
 - Preserve old `praisonai.*` import paths via shims when moving code between packages (see §2.3 in `src/praisonai-agents/AGENTS.md`; shim helpers in `src/praisonai/praisonai/cli/_shim.py`)
 - Package boundaries and dependency rules: `ARCHITECTURE.md` §2 (Tier 2 packages must never PyPI-depend on the wrapper; cross-tier access goes through lazy `_*_bridge` modules)
- Boundary manifests: `src/praisonai/tests/PRAISONAI_BOT_MANIFEST.md` (C9), `src/praisonai/tests/PRAISONAI_TRAIN_MANIFEST.md` (C10), `src/praisonai/tests/PRAISONAI_BROWSER_MANIFEST.md` (C11), `src/praisonai/tests/PRAISONAI_MCP_MANIFEST.md` (C12), `src/praisonai/tests/PRAISONAI_SANDBOX_MANIFEST.md` (C13)
+- Boundary manifests: `src/praisonai/tests/PRAISONAI_BOT_MANIFEST.md` (C9), `src/praisonai/tests/PRAISONAI_TRAIN_MANIFEST.md` (C10), `src/praisonai/tests/PRAISONAI_BROWSER_MANIFEST.md` (C11), `src/praisonai/tests/PRAISONAI_MCP_MANIFEST.md` (C12), `src/praisonai/tests/PRAISONAI_SANDBOX_MANIFEST.md` (C13), `src/praisonai/tests/PRAISONAI_DEPLOY_MANIFEST.md` (C14)
 - When reviewing a PR or an issue, evaluate whether the change addresses a framework concern or a user goal, and design its surface (params, naming, defaults) accordingly
 - The aim of this package is to stay **lightweight and powerful**. Do a critical review at each stage — when triaging an issue, when planning a fix, and when reviewing/implementing a PR. Reject scope creep for the sake of adding features: if a capability already exists (e.g. via existing Agent params like `instructions`/`backstory`/`tools`/`hooks`/`memory`), prefer it over a new API surface. A change must genuinely strengthen the SDK (simpler, more robust, more user-friendly) — do not add knobs, params, modules, or exports that have no live consumer or that merely duplicate existing behaviour.
@@ -1,6 +1,6 @@
 # PraisonAI Architecture

-> **Last updated:** 2026-07-17 (C13 — eight-package tiered model)
+> **Last updated:** 2026-07-31 (C14 — nine-package tiered model)
 >
 > Strategic architecture document for PraisonAI — a multi-agent AI framework.
 > Covers **Python tiered package model (C7.1 + C9 + C10)**, system design, runtime
@@ -11,7 +11,7 @@
 ## Table of Contents

 1. [Executive Summary](#1-executive-summary)
-2. [Python Tiered Package Model (C7.1 + C9 + C10 + C11 + C12 + C13)](#2-python-tiered-package-model-c71--c9--c10--c11--c12--c13)
+2. [Python Tiered Package Model (C7.1 + C9 + C10 + C11 + C12 + C13 + C14)](#2-python-tiered-package-model-c71--c9--c10--c11--c12--c13--c14)
 3. [System Overview](#3-system-overview)
 4. [Layered Architecture](#4-layered-architecture)
 5. [Core Data Contracts](#5-core-data-contracts)
@@ -51,17 +51,18 @@ Orchestration + Observability** core to unlock adoption and trust:

 ---

-## 2. Python Tiered Package Model (C7.1 + C9 + C10 + C11 + C12 + C13)
+## 2. Python Tiered Package Model (C7.1 + C9 + C10 + C11 + C12 + C13 + C14)

-**Release:** v4.6.110+ · `praisonaiagents` · `praisonai-code` · `praisonai-bot` · `praisonai-train` · `praisonai-browser` · `praisonai-mcp` · `praisonai-sandbox` · `praisonai`
+**Release:** v4.6.110+ · `praisonaiagents` · `praisonai-code` · `praisonai-bot` · `praisonai-train` · `praisonai-browser` · `praisonai-mcp` · `praisonai-sandbox` · `praisonai-deploy` · `praisonai`

-The Python monorepo publishes eight packages in three tiers with strict dependency
+The Python monorepo publishes nine packages in three tiers with strict dependency
 direction. C7 delivered a standalone agentic hot path; C7.1 formalised
 code/wrapper ownership; C9 extracted bots, gateway, and channel CLI into
 `praisonai-bot`; C10 extracted LLM fine-tuning and agent training into
 `praisonai-train`; C11 extracted browser automation into `praisonai-browser`;
 C12 extracted the heavy MCP host into `praisonai-mcp`.
 C13 extracted sandbox backends into `praisonai-sandbox`.
+C14 extracted deployment (API, Docker, cloud) into `praisonai-deploy`.

 ```mermaid
 flowchart TB
@@ -69,13 +70,14 @@ flowchart TB
    Agents["praisonaiagents<br/>Agent, tools, memory, hooks, protocols"]
  end

-  subgraph tier2 [Tier 2 — Terminal + Bot + Train + Browser + MCP + Sandbox]
+  subgraph tier2 [Tier 2 — Terminal + Bot + Train + Browser + MCP + Sandbox + Deploy]
    Code["praisonai-code<br/>run, chat, code, Typer, runtime, LLM"]
    Bot["praisonai-bot<br/>bots, gateway, channel CLI, OS daemon"]
    Train["praisonai-train<br/>LLM fine-tuning, agent training"]
    Browser["praisonai-browser<br/>extension bridge, CDP, Playwright"]
    MCP["praisonai-mcp<br/>MCP server host, auth, capability adapters"]
    Sandbox["praisonai-sandbox<br/>Docker, E2B, Modal, Sandlock backends"]
+    Deploy["praisonai-deploy<br/>API, Docker, AWS/Azure/GCP deploy"]
  end

  subgraph tier3 [Tier 3 — Wrapper]
@@ -88,36 +90,53 @@ flowchart TB
  Agents --> Browser
  Agents --> MCP
  Agents --> Sandbox
+  Agents --> Deploy
  Agents --> Wrapper
  Code -.->|"lazy _bot_bridge"| Bot
  Code -.->|"lazy _train_bridge"| Train
  Code -.->|"lazy _browser_bridge"| Browser
  Code -.->|"lazy _mcp_bridge"| MCP
  Code -.->|"lazy _sandbox_bridge"| Sandbox
+  Code -.->|"lazy _deploy_bridge"| Deploy
  Code -.->|"lazy _wrapper_bridge"| Wrapper
  Bot -.->|"lazy _code_bridge / _wrapper_bridge"| Code
  Bot -.->|"lazy _wrapper_bridge"| Wrapper
  Train -.->|"lazy _code_bridge / _wrapper_bridge"| Code
 ```

-**PyPI publish order:** `praisonaiagents` → `praisonai-code` + `praisonai-bot` + `praisonai-train` + `praisonai-browser` + `praisonai-mcp` + `praisonai-sandbox` → `praisonai`
+**PyPI publish order:** `praisonaiagents` → `praisonai-code` + `praisonai-bot` + `praisonai-train` + `praisonai-browser` + `praisonai-mcp` + `praisonai-sandbox` + `praisonai-deploy` → `praisonai`

 **Backward compatibility:** `praisonai.bots`, `praisonai.gateway`, `praisonai.train`,
-`praisonai.browser`, `praisonai.mcp_server`, `praisonai.sandbox`, and related CLI paths remain as
+`praisonai.browser`, `praisonai.mcp_server`, `praisonai.sandbox`, `praisonai.deploy`, and related CLI paths remain as
 `alias_package` shims to `praisonai_bot.*` / `praisonai_train.*` /
-`praisonai_browser.*` / `praisonai_mcp.*` / `praisonai_sandbox.*`.
+`praisonai_browser.*` / `praisonai_mcp.*` / `praisonai_sandbox.*` / `praisonai_deploy.*`.

 | Tier | Package | Owns | Must not depend on |
 |------|---------|------|-------------------|
-| 1 | `src/praisonai-agents/` | Agent, tools, memory, hooks, `frameworks/` protocols, sandbox protocols | `praisonai`, `praisonai-code`, `praisonai-bot`, `praisonai-train`, `praisonai-browser`, `praisonai-mcp`, `praisonai-sandbox` |
+| 1 | `src/praisonai-agents/` | Agent, tools, memory, hooks, `frameworks/` protocols, sandbox protocols | `praisonai`, `praisonai-code`, `praisonai-bot`, `praisonai-train`, `praisonai-browser`, `praisonai-mcp`, `praisonai-sandbox`, `praisonai-deploy` |
 | 2a | `src/praisonai-code/` | `run`/`chat`/`code`, Typer, runtime, LLM, tool resolution | **`praisonai` as a PyPI dependency** (optional lazy imports via `_wrapper_bridge` only) |
 | 2b | `src/praisonai-bot/` | Bots, gateway, channel CLI, OS daemon, gateway scheduler tick | **`praisonai` as a PyPI dependency** (optional lazy `_wrapper_bridge` for jobs/UI) |
 | 2c | `src/praisonai-train/` | LLM fine-tuning (Unsloth), agent training, `train` CLI, conda env setup | **`praisonai` as a PyPI dependency** (lazy `_code_bridge` for legacy dispatch) |
 | 2d | `src/praisonai-browser/` | Extension bridge, CDP/hybrid automation, `browser` CLI | **`praisonai` as a PyPI dependency** (none required; depends on `praisonaiagents` only) |
 | 2e | `src/praisonai-mcp/` | MCP server host, auth, transports, `mcp` CLI | **`praisonai` as a PyPI dependency** (lazy `_wrapper_bridge` for full capability registry) |
 | 2f | `src/praisonai-sandbox/` | Sandbox backends (Docker, E2B, Modal, Sandlock, SSH), `SandboxRegistry` | **`praisonai` as a PyPI dependency** (lazy `_code_bridge` for `PluginRegistry`) |
+| 2g | `src/praisonai-deploy/` | Deploy API/Docker/cloud, `deploy` CLI, scheduler integration | **`praisonai` as a PyPI dependency** (lazy `_plugin_registry` via `_code_bridge`) |
 | 3 | `src/praisonai/` | `framework_adapters/`, serve, dashboard, async jobs API | — |

+### Repo infra (not PyPI)
+
+Deployment packaging that stays in the git checkout, not in any tier-2 wheel:
+
+| Path | Runtime owner | Orchestration |
+|------|---------------|---------------|
+| `src/praisonai-bot/infra/helm/praisonai-gateway/` | `praisonai-bot` (gateway) | C14 `deploy helm` wrapper |
+| `src/praisonai-deploy/infra/helm/praisonai-agents-api/` | Generated API from C14 | C14 cross-link |
+| `src/praisonai-deploy/infra/compose/agents-stack/` | Docker Compose | `praisonai deploy compose up/down` |
+| `src/praisonai-deploy/infra/starters/` | Starter scaffolds | `praisonai deploy create --template` |
+| `docker/` | Mixed (wrapper/bot dev stacks) | Not C14 — see bot manifest for `docker/bots/` |
+
+Same boundary as C14: Helm/K8s manifests are **repo infra**, not `pip install praisonai-deploy` content.
+
 **Config kernel:** Phase 0 `praisonai/common/` was skipped; shared config lives in
 `praisonai_code/cli/configuration/` and is reached by the bot tier via lazy
 `_code_bridge` (see `src/praisonai/tests/CONFIG_KERNEL.md`).
@@ -25,7 +25,7 @@ Methods:

 Types:
 ```python
-from praisonaiagents import Agent, AutoAgents, AutoRagAgent, ContextAgent, DeepResearchAgent, ImageAgent, PlanningAgent, PromptExpanderAgent, QueryRewriterAgent, create_context_agent
+from praisonaiagents import Agent, AutoAgents, AutoRagAgent, ContextAgent, DeepResearchAgent, ImageAgent, PlanningAgent, PraisonAIAgents, PromptExpanderAgent, QueryRewriterAgent, create_context_agent
 ```

 Methods:
@@ -36,13 +36,9 @@ Methods:
 * <code title="class Agent">Agent.<a href="./src/praisonai-agents/praisonaiagents/agent/agent.py">analyze_prompt</a>(prompt: str) -> set</code>
 * <code title="class Agent">Agent.<a href="./src/praisonai-agents/praisonaiagents/agent/agent.py">auto_memory</a>() -> Optional[bool]</code>
 * <code title="class Agent">Agent.<a href="./src/praisonai-agents/praisonaiagents/agent/agent.py">auto_memory</a>(value: Optional[bool]) -> None</code>
-* <code title="class Agent">Agent.<a href="./src/praisonai-agents/praisonaiagents/agent/agent.py">background</a>() -> Optional[bool]</code>
-* <code title="class Agent">Agent.<a href="./src/praisonai-agents/praisonaiagents/agent/agent.py">background</a>(value: Optional[bool]) -> None</code>
 * <code title="class Agent">Agent.<a href="./src/praisonai-agents/praisonaiagents/agent/agent.py">chat_history</a>()</code>
 * <code title="class Agent">Agent.<a href="./src/praisonai-agents/praisonaiagents/agent/agent.py">chat_history</a>(value)</code>
 * <code title="class Agent">Agent.<a href="./src/praisonai-agents/praisonaiagents/agent/agent.py">chat_with_context</a>(message: str, context: 'ContextPack', **kwargs) -> str</code>
-* <code title="class Agent">Agent.<a href="./src/praisonai-agents/praisonaiagents/agent/agent.py">checkpoints</a>() -> Optional[bool]</code>
-* <code title="class Agent">Agent.<a href="./src/praisonai-agents/praisonaiagents/agent/agent.py">checkpoints</a>(value: Optional[bool]) -> None</code>
 * <code title="class Agent">Agent.<a href="./src/praisonai-agents/praisonaiagents/agent/agent.py">clone_for_channel</a>() -> 'Agent'</code>
 * <code title="class Agent">Agent.<a href="./src/praisonai-agents/praisonaiagents/agent/agent.py">close</a>() -> None</code>
 * <code title="class Agent">Agent.<a href="./src/praisonai-agents/praisonaiagents/agent/agent.py">console</a>() -> Optional[Any]</code>
@@ -83,6 +79,7 @@ Methods:
 * <code title="class Agent">Agent.<a href="./src/praisonai-agents/praisonaiagents/agent/agent.py">run_autonomous_async</a>(prompt: str, max_iterations: Optional[int] = None, timeout_seconds: Optional[float] = None, completion_promise: Optional[str] = None, clear_context: bool = False)</code>
 * <code title="class Agent">Agent.<a href="./src/praisonai-agents/praisonaiagents/agent/agent.py">run_until</a>(prompt: str, criteria: str = '', threshold: float = 8.0, max_iterations: int = 5, mode: str = 'optimize', on_iteration: Optional[Callable[[Any], None]] = None, verbose: bool = False, goal: Optional[str] = None, goal_criteria: Optional[Any] = None, judge_model: Optional[str] = None) -> 'EvaluationLoopResult'</code>
 * <code title="class Agent">Agent.<a href="./src/praisonai-agents/praisonaiagents/agent/agent.py">run_until_async</a>(prompt: str, criteria: str, threshold: float = 8.0, max_iterations: int = 5, mode: str = 'optimize', on_iteration: Optional[Callable[[Any], None]] = None, verbose: bool = False) -> 'EvaluationLoopResult'</code>
+* <code title="class Agent">Agent.<a href="./src/praisonai-agents/praisonaiagents/agent/agent.py">set_snapshot_root</a>(project_path: str) -> bool</code>
 * <code title="class Agent">Agent.<a href="./src/praisonai-agents/praisonaiagents/agent/agent.py">skill_manager</a>() -> Optional[Any]</code>
 * <code title="class Agent">Agent.<a href="./src/praisonai-agents/praisonaiagents/agent/agent.py">store_memory</a>(content: str, memory_type: str = 'short_term', action: str = 'add', **kwargs: Any) -> None</code>
 * <code title="class Agent">Agent.<a href="./src/praisonai-agents/praisonaiagents/agent/agent.py">stream_emitter</a>() -> Optional[Any]</code>
@@ -179,14 +176,15 @@ Methods:
 * <code title="class BaseTool">BaseTool.<a href="./src/praisonai-agents/praisonaiagents/tools/base.py">get_schema</a>() -> Dict[str, Any]</code>
 * <code title="class BaseTool">BaseTool.<a href="./src/praisonai-agents/praisonaiagents/tools/base.py">run</a>(**kwargs) -> Any</code>
 * <code title="class BaseTool">BaseTool.<a href="./src/praisonai-agents/praisonaiagents/tools/base.py">safe_run</a>(**kwargs) -> ToolResult</code>
+* <code title="class BaseTool">BaseTool.<a href="./src/praisonai-agents/praisonaiagents/tools/base.py">to_model_output</a>(result: Any) -> Optional[Any]</code>
 * <code title="class BaseTool">BaseTool.<a href="./src/praisonai-agents/praisonaiagents/tools/base.py">validate</a>() -> bool</code>
 * <code title="class BaseTool">BaseTool.<a href="./src/praisonai-agents/praisonaiagents/tools/base.py">validate_class</a>() -> bool</code>
 * <code title="class BaseTool">BaseTool.<a href="./src/praisonai-agents/praisonaiagents/tools/base.py">validate_schema_roundtrip</a>() -> bool</code>
 * <code title="class FunctionTool">FunctionTool.<a href="./src/praisonai-agents/praisonaiagents/tools/decorator.py">__call__</a>(*args, **kwargs) -> Any</code>
 * <code title="class FunctionTool">FunctionTool.<a href="./src/praisonai-agents/praisonaiagents/tools/decorator.py">check_availability</a>() -> tuple[bool, str]</code>
-* <code title="class FunctionTool">FunctionTool.<a href="./src/praisonai-agents/praisonaiagents/tools/decorator.py">get_schema</a>() -> Dict[str, Any]</code>
 * <code title="class FunctionTool">FunctionTool.<a href="./src/praisonai-agents/praisonaiagents/tools/decorator.py">injected_params</a>() -> Dict[str, Any]</code>
 * <code title="class FunctionTool">FunctionTool.<a href="./src/praisonai-agents/praisonaiagents/tools/decorator.py">run</a>(**kwargs) -> Any</code>
+* <code title="class FunctionTool">FunctionTool.<a href="./src/praisonai-agents/praisonaiagents/tools/decorator.py">to_model_output</a>(result: Any) -> Optional[Any]</code>
 * <code title="class ToolRegistry">ToolRegistry.<a href="./src/praisonai-agents/praisonaiagents/tools/registry.py">clear</a>() -> None</code>
 * <code title="class ToolRegistry">ToolRegistry.<a href="./src/praisonai-agents/praisonaiagents/tools/registry.py">discover_plugins</a>() -> int</code>
 * <code title="class ToolRegistry">ToolRegistry.<a href="./src/praisonai-agents/praisonaiagents/tools/registry.py">discover_single_file_plugins</a>() -> int</code>
@@ -252,9 +250,12 @@ Methods:
 * <code title="class Memory">Memory.<a href="./src/praisonai-agents/praisonaiagents/memory/memory.py">delete_memory</a>(memory_id: str, memory_type: Optional[str] = None) -> bool</code>
 * <code title="class Memory">Memory.<a href="./src/praisonai-agents/praisonaiagents/memory/memory.py">delete_short_term</a>(memory_id: str) -> bool</code>
 * <code title="class Memory">Memory.<a href="./src/praisonai-agents/praisonaiagents/memory/memory.py">finalize_task_output</a>(content: str, agent_name: str, quality_score: float, threshold: float = 0.7, metrics: Dict[str, Any] = None, task_id: str = None)</code>
+* <code title="class Memory">Memory.<a href="./src/praisonai-agents/praisonaiagents/memory/memory.py">forget</a>(**kwargs) -> int</code>
 * <code title="class Memory">Memory.<a href="./src/praisonai-agents/praisonaiagents/memory/memory.py">get_all_memories</a>() -> List[Dict[str, Any]]</code>
 * <code title="class Memory">Memory.<a href="./src/praisonai-agents/praisonaiagents/memory/memory.py">get_learn_context</a>() -> str</code>
 * <code title="class Memory">Memory.<a href="./src/praisonai-agents/praisonaiagents/memory/memory.py">learn</a>()</code>
+* <code title="class Memory">Memory.<a href="./src/praisonai-agents/praisonaiagents/memory/memory.py">recall</a>(query: str, **kwargs) -> List[Dict[str, Any]]</code>
+* <code title="class Memory">Memory.<a href="./src/praisonai-agents/praisonaiagents/memory/memory.py">remember</a>(content: str, **kwargs) -> str</code>
 * <code title="class Memory">Memory.<a href="./src/praisonai-agents/praisonaiagents/memory/memory.py">reset_all</a>()</code>
 * <code title="class Memory">Memory.<a href="./src/praisonai-agents/praisonaiagents/memory/memory.py">reset_entity_only</a>()</code>
 * <code title="class Memory">Memory.<a href="./src/praisonai-agents/praisonaiagents/memory/memory.py">reset_long_term</a>()</code>
@@ -509,6 +510,7 @@ Methods:
 * <code title="class SkillManager">SkillManager.<a href="./src/praisonai-agents/praisonaiagents/skills/manager.py">patch</a>(name: str, old_string: str, new_string: str, file_path: Optional[str] = None, replace_all: bool = False, propose: Optional[bool] = None) -> dict</code>
 * <code title="class SkillManager">SkillManager.<a href="./src/praisonai-agents/praisonaiagents/skills/manager.py">patch_skill</a>(name: str, old_string: str, new_string: str, file_path: str = None, replace_all: bool = False, propose: Optional[bool] = None) -> dict</code>
 * <code title="class SkillManager">SkillManager.<a href="./src/praisonai-agents/praisonaiagents/skills/manager.py">reject</a>(identifier: str) -> dict</code>
+* <code title="class SkillManager">SkillManager.<a href="./src/praisonai-agents/praisonaiagents/skills/manager.py">reload</a>() -> Dict[str, List[str]]</code>
 * <code title="class SkillManager">SkillManager.<a href="./src/praisonai-agents/praisonaiagents/skills/manager.py">remove_file</a>(name: str, file_path: str, propose: Optional[bool] = None) -> dict</code>
 * <code title="class SkillManager">SkillManager.<a href="./src/praisonai-agents/praisonaiagents/skills/manager.py">remove_skill_file</a>(name: str, file_path: str, propose: Optional[bool] = None) -> dict</code>
 * <code title="class SkillManager">SkillManager.<a href="./src/praisonai-agents/praisonaiagents/skills/manager.py">resolve</a>(selectors: List[str]) -> List[str]</code>
@@ -568,6 +570,7 @@ Methods:
 * <code title="class MCP">MCP.<a href="./src/praisonai-agents/praisonaiagents/mcp/mcp.py">get_prompts</a>() -> List[dict]</code>
 * <code title="class MCP">MCP.<a href="./src/praisonai-agents/praisonaiagents/mcp/mcp.py">get_resources</a>() -> List[dict]</code>
 * <code title="class MCP">MCP.<a href="./src/praisonai-agents/praisonaiagents/mcp/mcp.py">get_tools</a>() -> List[Callable]</code>
+* <code title="class MCP">MCP.<a href="./src/praisonai-agents/praisonaiagents/mcp/mcp.py">list_active_server_names</a>() -> set</code>
 * <code title="class MCP">MCP.<a href="./src/praisonai-agents/praisonaiagents/mcp/mcp.py">shutdown</a>()</code>
 * <code title="class MCP">MCP.<a href="./src/praisonai-agents/praisonaiagents/mcp/mcp.py">to_openai_tool</a>()</code>
 * <code title="class MCP">MCP.<a href="./src/praisonai-agents/praisonaiagents/mcp/mcp.py">with_tool_prefix</a>(prefix: str) -> 'MCP'</code>
@@ -731,7 +734,7 @@ Methods:

 Types:
 ```python
-from praisonaiagents import AgentAppConfig, AgentAppProtocol, AgentFlow, AgentManager, AgentOSConfig, AgentOSProtocol, AgentTeam, AutoApproveBackend, EmbeddingResult, RetryBackoffConfig, __version__, aembedding, aembeddings, embedding, embeddings, get_dimensions
+from praisonaiagents import AgentAppConfig, AgentAppProtocol, AgentFlow, AgentManager, AgentOSConfig, AgentOSProtocol, AgentTeam, AutoApproveBackend, EmbeddingResult, RetryBackoffConfig, RunOutcome, __version__, aembedding, aembeddings, embedding, embeddings, get_dimensions
 ```

 Methods:
@@ -765,6 +768,7 @@ Methods:
 * <code title="class AgentTeam">AgentTeam.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">arun_task</a>(task_id)</code>
 * <code title="class AgentTeam">AgentTeam.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">aspawn_sub_agent</a>(agent: Agent, task: Any, completion_callback: Optional[Callable[[SubAgentCompletionEvent], Any]] = None, metadata: Optional[Dict[str, Any]] = None) -> SpawnedSubAgent</code>
 * <code title="class AgentTeam">AgentTeam.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">astart</a>(content = None, return_dict = False, **kwargs)</code>
+* <code title="class AgentTeam">AgentTeam.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">astart_for_each</a>(inputs, **kwargs)</code>
 * <code title="class AgentTeam">AgentTeam.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">await_for_completions</a>(timeout: Optional[float] = None, agent_ids: Optional[List[str]] = None) -> List[SubAgentCompletionEvent]</code>
 * <code title="class AgentTeam">AgentTeam.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">clean_json_output</a>(output: str) -> str</code>
 * <code title="class AgentTeam">AgentTeam.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">clear_state</a>() -> None</code>
@@ -795,16 +799,21 @@ Methods:
 * <code title="class AgentTeam">AgentTeam.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">run_all_tasks</a>()</code>
 * <code title="class AgentTeam">AgentTeam.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">run_task</a>(task_id)</code>
 * <code title="class AgentTeam">AgentTeam.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">save_output_to_file</a>(task, task_output)</code>
-* <code title="class AgentTeam">AgentTeam.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">save_session_state</a>(session_id: str, include_memory: bool = True) -> None</code>
+* <code title="class AgentTeam">AgentTeam.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">save_session_state</a>(session_id: str, include_memory: bool = True) -> bool</code>
 * <code title="class AgentTeam">AgentTeam.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">set_state</a>(key: str, value: Any) -> None</code>
 * <code title="class AgentTeam">AgentTeam.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">spawn_sub_agent</a>(agent: Agent, task: Any, completion_callback: Optional[Callable[[SubAgentCompletionEvent], Any]] = None, metadata: Optional[Dict[str, Any]] = None) -> SpawnedSubAgent</code>
 * <code title="class AgentTeam">AgentTeam.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">start</a>(content = None, return_dict = False, output = None, **kwargs)</code>
+* <code title="class AgentTeam">AgentTeam.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">start_for_each</a>(inputs, **kwargs)</code>
+* <code title="class AgentTeam">AgentTeam.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">stream_emitter</a>()</code>
 * <code title="class AgentTeam">AgentTeam.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">todo_list</a>()</code>
 * <code title="class AgentTeam">AgentTeam.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">update_plan_step_status</a>(step_id: str, status: str) -> bool</code>
 * <code title="class AgentTeam">AgentTeam.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">update_state</a>(updates: Dict) -> None</code>
 * <code title="class AgentTeam">AgentTeam.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">wait_for_completions</a>(timeout: Optional[float] = None, agent_ids: Optional[List[str]] = None) -> List[SubAgentCompletionEvent]</code>
 * <code title="class AutoApproveBackend">AutoApproveBackend.<a href="./src/praisonai-agents/praisonaiagents/approval/backends.py">request_approval</a>(request: ApprovalRequest) -> ApprovalDecision</code>
 * <code title="class AutoApproveBackend">AutoApproveBackend.<a href="./src/praisonai-agents/praisonaiagents/approval/backends.py">request_approval_sync</a>(request: ApprovalRequest) -> ApprovalDecision</code>
+* <code title="class RunOutcome">RunOutcome.<a href="./src/praisonai-agents/praisonaiagents/agent/run_outcome.py">completed</a>(output: Optional[str] = None) -> 'RunOutcome'</code>
+* <code title="class RunOutcome">RunOutcome.<a href="./src/praisonai-agents/praisonaiagents/agent/run_outcome.py">from_exception</a>(exc: BaseException, output: Optional[str] = None) -> 'RunOutcome'</code>
+* <code title="class RunOutcome">RunOutcome.<a href="./src/praisonai-agents/praisonaiagents/agent/run_outcome.py">succeeded</a>() -> bool</code>
 * <code title="function">praisonaiagents.<a href="./src/praisonai-agents/praisonaiagents/embedding/embed.py">aembedding</a>(input: Union[str, List[str]], model: str = 'text-embedding-3-small', dimensions: Optional[int] = None, encoding_format: str = 'float', timeout: float = 600.0, api_key: Optional[str] = None, api_base: Optional[str] = None, metadata: Optional[Dict[str, Any]] = None, **kwargs) -> EmbeddingResult</code>
 * <code title="function">praisonaiagents.<a href="./src/praisonai-agents/praisonaiagents/embedding/embed.py">aembeddings</a>(input: Union[str, List[str]], model: str = 'text-embedding-3-small', dimensions: Optional[int] = None, encoding_format: str = 'float', timeout: float = 600.0, api_key: Optional[str] = None, api_base: Optional[str] = None, metadata: Optional[Dict[str, Any]] = None, **kwargs) -> EmbeddingResult</code>
 * <code title="function">praisonaiagents.<a href="./src/praisonai-agents/praisonaiagents/embedding/dimensions.py">get_dimensions</a>(model_name: str) -> int</code>
@@ -813,7 +822,7 @@ Methods:

 Types:
 ```python
-from praisonai import Agent, AgentApp, AgentOS, AnthropicManagedAgent, CloudProvider, DB, Deploy, DeployConfig, DeployType, HostedAgent, HostedAgentConfig, LocalAgent, LocalAgentConfig, LocalManagedAgent, LocalManagedConfig, ManagedAgent, ManagedConfig, __version__, arun, run
+from praisonai import Agent, AgentApp, AgentOS, AnthropicManagedAgent, DB, HostedAgent, HostedAgentConfig, LocalAgent, LocalAgentConfig, LocalManagedAgent, LocalManagedConfig, ManagedAgent, ManagedConfig, __version__, arun, run
 ```

 # CLI
@@ -0,0 +1,10 @@
+# Deployment infra has moved
+
+Deployment assets are no longer at the monorepo root.
+
+| Asset | New location |
+|-------|----------------|
+| Gateway Helm chart | [`src/praisonai-bot/infra/helm/praisonai-gateway/`](../src/praisonai-bot/infra/helm/praisonai-gateway/) |
+| Agents API Helm, Compose, Starters | [`src/praisonai-deploy/infra/`](../src/praisonai-deploy/infra/) |
+
+See [`src/praisonai-deploy/infra/README.md`](../src/praisonai-deploy/infra/README.md).
@@ -16,7 +16,7 @@ RUN mkdir -p /root/.praison
 # Install Python packages (using latest versions)
 RUN pip install --no-cache-dir \
    praisonai_tools \
-    "praisonai>=4.6.155" \
+    "praisonai>=4.6.162" \
    "praisonai[chat]" \
    "embedchain[github,youtube]"

@@ -20,7 +20,7 @@ RUN mkdir -p /root/.praison
 # Install Python packages (using latest versions)
 RUN pip install --no-cache-dir \
    praisonai_tools \
-    "praisonai>=4.6.155" \
+    "praisonai>=4.6.162" \
    "praisonai[ui]" \
    "praisonai[chat]" \
    "praisonai[realtime]" \
@@ -16,7 +16,7 @@ RUN mkdir -p /root/.praison
 # Install Python packages (using latest versions)
 RUN pip install --no-cache-dir \
    praisonai_tools \
-    "praisonai>=4.6.155" \
+    "praisonai>=4.6.162" \
    "praisonai[ui]" \
    "praisonai[crewai]"

@@ -36,6 +36,12 @@ if __name__ == "__main__":
    print(f"Custom agent max_rpm: {agent.max_rpm}")
    print(f"Custom agent max_execution_time: {agent.max_execution_time}")
    print(f"Custom agent max_retry_limit: {agent.max_retry_limit}")
+
+    # max_rpm auto-creates a live RateLimiter (not just a stored number)
+    assert agent_rate_limited.max_rpm == 10
+    assert agent_rate_limited._rate_limiter is not None
+    assert agent_rate_limited._rate_limiter.requests_per_minute == 10
+    print(f"Rate-limited agent limiter: {agent_rate_limited._rate_limiter}")
    
    # Test custom agent
    print("\n--- Custom Execution ---")
@@ -0,0 +1,111 @@
+"""
+Human Review Between Sequential AgentTeam Tasks
+================================================
+
+Demonstrates a human-in-the-loop review gate between sequential tasks using the
+existing ``on_task_complete`` hook — no new API required.
+
+IMPORTANT — two different ``on_task_complete`` hooks exist, with DIFFERENT
+signatures. Do not confuse them:
+
+    AgentTeam(hooks=MultiAgentHooksConfig(on_task_complete=fn))
+        -> fn(task, task_output)          # team-level; gets the Task and its output
+
+    Task(on_task_complete=fn)
+        -> fn(task_output)                # 1 param: just the TaskOutput
+        -> fn(task_output, metadata)      # 2+ params: TaskOutput + metadata dict
+                                          #   NOTE: NOT (task, task_output)
+
+This example uses the TEAM-level hook so we get ``(task, task_output)`` and can
+filter which tasks require review by ``task.name``.
+
+Approve / reject / edit:
+- approve -> return, workflow continues
+- reject  -> raise; see "stopping the workflow" note below
+- edit    -> mutate ``task_output.raw``; downstream tasks that read this task via
+             ``context=[...]`` pick up the edited text
+
+Stopping the workflow on reject
+-------------------------------
+The TEAM-level hook logs and swallows exceptions, so a bare ``raise`` inside it
+does NOT stop the sequential run today. To hard-stop on reject, use the PER-TASK
+callback path with the 1-argument signature and ``fail_on_callback_error=True``
+(see ``review_output`` / ``t1_strict`` at the bottom of this file).
+"""
+
+from praisonaiagents import Agent, Task, AgentTeam
+from praisonaiagents.config.feature_configs import MultiAgentHooksConfig
+
+# Only these task names trigger a human review gate.
+REVIEW_TASKS = {"research"}
+
+
+# --- Team-level review gate: signature is (task, task_output) ---------------
+def review_gate(task, task_output):
+    if task.name not in REVIEW_TASKS:
+        return
+
+    print(f"\n--- Review: {task.name} ---\n{task_output.raw}\n")
+    choice = input("Approve (y), reject (n), edit (e)? ").strip().lower()
+
+    if choice == "n":
+        # NOTE: team-level hook swallows this; see per-task strict path below
+        # for a version that actually halts the workflow.
+        raise RuntimeError(f"Human rejected task '{task.name}'")
+
+    if choice == "e":
+        # task.result is the same object as task_output, so mutating .raw here
+        # propagates to downstream tasks that use context=[this_task].
+        task_output.raw = input("Edited output: ").strip()
+
+
+researcher = Agent(name="Researcher", role="Researcher", goal="Research", backstory="Expert")
+writer = Agent(name="Writer", role="Writer", goal="Write", backstory="Writer")
+
+t1 = Task(
+    name="research",
+    description="List 5 facts about {{topic}}",  # {{...}} is the substitution syntax
+    expected_output="5 bullets",
+    agent=researcher,
+)
+t2 = Task(
+    name="summary",
+    description="Write 3-sentence summary",
+    expected_output="3 sentences",
+    agent=writer,
+    context=[t1],  # reads the (possibly edited) output of t1
+)
+
+team = AgentTeam(
+    agents=[researcher, writer],
+    tasks=[t1, t2],
+    process="sequential",
+    variables={"topic": "REST APIs"},  # substituted into {{topic}} in task descriptions
+    hooks=MultiAgentHooksConfig(on_task_complete=review_gate),
+)
+
+
+# --- Alternative: per-task strict gate that HALTS on reject -----------------
+# Per-task Task.on_task_complete uses the 1-argument signature (task_output).
+# With fail_on_callback_error=True a raised exception re-raises and stops the run.
+def review_output(task_output):
+    print(f"\n--- Review output ---\n{task_output.raw}\n")
+    if input("Approve? (y/n) ").strip().lower() == "n":
+        raise RuntimeError("Human rejected output")
+
+
+t1_strict = Task(
+    name="research",
+    description="List 5 facts about {{topic}}",
+    expected_output="5 bullets",
+    agent=researcher,
+    variables={"topic": "REST APIs"},
+    on_task_complete=review_output,     # signature: (task_output)
+    fail_on_callback_error=True,        # required so reject halts the workflow
+)
+
+
+if __name__ == "__main__":
+    # NOTE: template values come from AgentTeam(variables=...), NOT start(inputs=...).
+    # start() forwards **kwargs but does not consume an ``inputs`` argument.
+    team.start()
@@ -86,7 +86,7 @@ def method_1_simple_loop():
        agents=[loop_agent],
        tasks=[loop_task],
        process="workflow",
-        max_iter=10                 # Maximum iterations to prevent infinite loops
+        execution="balanced"        # max_iter=10 preset to prevent infinite loops
    )
    
    print(f"🚀 Starting loop processing of {csv_file}")
@@ -64,7 +64,7 @@ def main():
        agents=[url_agent],
        tasks=[url_task],
        process="workflow",
-        max_iter=10  # Adjust based on how many URLs you have
+        execution="balanced"  # max_iter=10 preset; adjust for more URLs
    )
    
    print(f"🚀 Processing URLs from {csv_file}")
@@ -141,7 +141,7 @@ class DynamicAgentSystem:
            agents=agents,
            tasks=tasks,
            process=process,
-            verbose=inputs['depth'] == 'detailed'
+            output="verbose" if inputs['depth'] == 'detailed' else "silent"
        )
        
        result = praison_agents.start()
@@ -66,7 +66,7 @@ research_task1 = Task(
 agents_session1 = AgentTeam(
    agents=[research_agent],
    tasks=[research_task1],
-    session=session1, output="verbose"
+    output="verbose"
 )

 # Execute first session
@@ -105,7 +105,7 @@ analysis_task = Task(
 agents_session2 = AgentTeam(
    agents=[analysis_agent],
    tasks=[analysis_task], 
-    session=session2, output="verbose"
+    output="verbose"
 )

 print("Starting analysis session with previous context...")
@@ -155,7 +155,7 @@ synthesis_task = Task(
 agents_recovery = AgentTeam(
    agents=[synthesis_agent],
    tasks=[synthesis_task],
-    session=recovery_session, output="verbose"
+    output="verbose"
 )

 print("Starting recovery session with full context from previous sessions...")
@@ -205,7 +205,7 @@ review_task = Task(
 agents_reviewer = AgentTeam(
    agents=[review_agent],
    tasks=[review_task],
-    session=reviewer_session, output="verbose"
+    output="verbose"
 )

 print("Starting peer review session by different user...")
@@ -14,18 +14,18 @@ def test_imports():
    """Test that all required modules can be imported."""
    try:
        from praisonaiagents import Agent
-        print("✅ Agent imported successfully")
+        print("[OK] Agent imported successfully")
        
        from praisonaiagents.tools import execute_command
-        print("✅ execute_command tool imported successfully")
+        print("[OK] execute_command tool imported successfully")
        
        from praisonaiagents.approval import get_approval_registry, AutoApproveBackend
-        print("✅ Approval system imported successfully")
+        print("[OK] Approval system imported successfully")
        
        return True
        
    except ImportError as e:
-        print(f"❌ Import failed: {e}")
+        print(f"[FAIL] Import failed: {ascii(e)}")
        return False

 def test_agent_creation():
@@ -40,11 +40,11 @@ def test_agent_creation():
        )
        
        assert agent.name == 'test-agent'
-        print("✅ Agent creation successful")
+        print("[OK] Agent creation successful")
        return True
        
    except Exception as e:
-        print(f"❌ Agent creation failed: {e}")
+        print(f"[FAIL] Agent creation failed: {ascii(e)}")
        return False

 def test_approval_system():
@@ -55,11 +55,11 @@ def test_approval_system():
        registry = get_approval_registry()
        registry.set_backend(AutoApproveBackend())
        
-        print("✅ Approval system configuration successful")
+        print("[OK] Approval system configuration successful")
        return True
        
    except Exception as e:
-        print(f"❌ Approval system test failed: {e}")
+        print(f"[FAIL] Approval system test failed: {ascii(e)}")
        return False

 def test_external_agent_import():
@@ -80,11 +80,11 @@ def test_external_agent_import():
        
        # Now try to import our agent
        import praisonai_external_agent
-        print("✅ External agent import successful")
+        print("[OK] External agent import successful")
        return True
        
    except Exception as e:
-        print(f"❌ External agent import failed: {e}")
+        print(f"[FAIL] External agent import failed: {ascii(e)}")
        return False

 def test_multi_agent_import():
@@ -104,11 +104,11 @@ def test_multi_agent_import():
        sys.modules['harbor.models.agent.context'] = MagicMock()
        
        import multi_agent_example
-        print("✅ Multi-agent example import successful")
+        print("[OK] Multi-agent example import successful")
        return True
        
    except Exception as e:
-        print(f"❌ Multi-agent example import failed: {e}")
+        print(f"[FAIL] Multi-agent example import failed: {ascii(e)}")
        return False

 def test_wrapper_agent_import():
@@ -128,11 +128,11 @@ def test_wrapper_agent_import():
        sys.modules['harbor.models.agent.context'] = MagicMock()
        
        import praisonai_wrapper_agent
-        print("✅ Wrapper agent import successful (CLI-based approach)")
+        print("[OK] Wrapper agent import successful (CLI-based approach)")
        return True
        
    except Exception as e:
-        print(f"❌ Wrapper agent import failed: {e}")
+        print(f"[FAIL] Wrapper agent import failed: {ascii(e)}")
        return False

 if __name__ == "__main__":
@@ -152,19 +152,19 @@ if __name__ == "__main__":
    total = len(tests)
    
    for test_name, test_func in tests:
-        print(f"\n🧪 Testing {test_name}...")
+        print(f"\n[TEST] {test_name}...")
        try:
            if test_func():
                passed += 1
        except Exception as e:
-            print(f"❌ Test {test_name} crashed: {e}")
+            print(f"[FAIL] Test {test_name} crashed: {ascii(e)}")
    
    print("\n" + "=" * 55)
    print(f"Results: {passed}/{total} tests passed")
    
    if passed == total:
-        print("🎉 ALL BASIC TESTS PASSED!")
+        print("[OK] ALL BASIC TESTS PASSED!")
        print("The Terminal-Bench integration components are properly structured.")
    else:
-        print("❌ Some tests failed - check output above")
+        print("[FAIL] Some tests failed - check output above")
        sys.exit(1)
@@ -0,0 +1,64 @@
+# Simple Sequential Team (YAML)
+
+A minimal 2-agent sequential team: a **researcher** gathers facts, then a
+**writer** summarizes them. This is the copy-paste starting point for the most
+common multi-agent pattern (2–5 agents, run in order).
+
+```
+research_task  ->  summary_task
+ (researcher)       (writer)
+```
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `agents.yaml` | Roles (who) + their tasks (what); tasks run in declaration order |
+
+> **Which loader applies?** This example uses the canonical single-file format
+> consumed by `AgentsGenerator.generate_crew_and_kickoff()`
+> (`src/praisonai/praisonai/agents_generator.py`). Agents live under `roles:`,
+> each with nested `tasks:`. **Tasks run in the order they are declared** — the
+> researcher's task first, then the writer's. (An optional top-level
+> `dependencies:` block is included to document intent and mirror the canonical
+> fixture, but the roles-file loader sequences by declaration order, so keep
+> tasks in the order you want them to run.) No new loader module is required —
+> this is the existing YAML path.
+
+## Run it
+
+```bash
+export OPENAI_API_KEY=sk-...
+praisonai examples/yaml/teams/research-writer/agents.yaml
+```
+
+This positional-file form is the canonical roles-file entry point. From Python
+the equivalent is `praisonai.run("agents.yaml")` (see
+`src/praisonai/praisonai/_entrypoint.py`), which dispatches to the same
+`AgentsGenerator`.
+
+Change the subject by editing the `topic:` line in `agents.yaml` (interpolated
+into every `{topic}` placeholder).
+
+## When to use this vs a workflow YAML
+
+| You need… | Use | Example |
+|-----------|-----|---------|
+| 2–5 agents, sequential/hierarchical | **This** (`roles:` + `tasks:`) | `agents.yaml` here |
+| Routing by classifier output | workflow YAML | `../../workflows/routing_workflow.yaml` |
+| Parallel branches | workflow YAML | `../../workflows/parallel_workflow.yaml` |
+| Loops / planning / memory | workflow YAML | `../../workflows/complete_workflow.yaml` |
+
+## Python equivalent
+
+```python
+from praisonaiagents import Agent, Task, PraisonAIAgents
+
+researcher = Agent(role="Senior Researcher", goal="Find accurate information")
+writer = Agent(role="Report Writer", goal="Turn research into summaries")
+
+t1 = Task(description="Research renewable energy and list 5 key facts", agent=researcher)
+t2 = Task(description="Write a 3-sentence summary from the research", agent=writer, context=[t1])
+
+PraisonAIAgents(agents=[researcher, writer], tasks=[t1, t2]).start()
+```
@@ -0,0 +1,34 @@
+# yaml-language-server: $schema=https://docs.praison.ai/schemas/agents.schema.json
+# Minimal sequential team: researcher -> writer
+# Run: praisonai examples/yaml/teams/research-writer/agents.yaml
+
+framework: "praisonai"
+topic: "renewable energy"
+
+roles:
+  researcher:
+    role: "Senior Researcher"
+    goal: "Find accurate information about {topic}"
+    backstory: "Expert at concise, factual research."
+    tasks:
+      research_task:
+        description: "Research {topic} and list 5 key facts."
+        expected_output: "A bullet list of 5 facts."
+
+  writer:
+    role: "Report Writer"
+    goal: "Turn research into readable summaries about {topic}"
+    backstory: "Clear technical writer."
+    tasks:
+      summary_task:
+        description: "Write a 3-sentence executive summary from the research."
+        expected_output: "3 sentences, plain text."
+
+# Ordering is by task declaration order above (researcher's task runs first,
+# then the writer's), which is how the roles-file loader sequences tasks.
+# The optional `dependencies:` block below mirrors the canonical fixture
+# (src/praisonai/tests/agents.yaml) and documents intent; the roles-file
+# loader does not consume it, so keep tasks in the order you want them run.
+dependencies:
+  - task: summary_task
+    depends_on: research_task
@@ -0,0 +1,55 @@
+#!/usr/bin/env bash
+# C14 import-direction gate for praisonai-deploy.
+set -euo pipefail
+
+cd "$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+
+CODE_ROOT="${C14_CODE_ROOT:-src/praisonai-code/praisonai_code}"
+DEPLOY_ROOT="${C14_DEPLOY_ROOT:-src/praisonai-deploy/praisonai_deploy}"
+
+ANY_WRAPPER_RE='(^[[:space:]]*from praisonai([[:space:]]|\.)|^[[:space:]]*import praisonai($|\.))'
+ANY_CODE_RE='(^from praisonai_code([[:space:]]|\.)|^import praisonai_code($|\.))'
+ANY_DEPLOY_RE='(^[[:space:]]*from praisonai_deploy([[:space:]]|\.)|^[[:space:]]*import praisonai_deploy($|\.))'
+
+echo "== C14 praisonai_deploy wrapper import gate (must be zero outside bridges) =="
+if command -v rg >/dev/null 2>&1; then
+  MATCHES="$(rg -n "$ANY_WRAPPER_RE" "$DEPLOY_ROOT" --glob '*.py' 2>/dev/null | grep -v '_wrapper_bridge.py' | grep -v '_bootstrap.py' | grep -v '_code_bridge.py' || true)"
+else
+  MATCHES="$(grep -rEn --include='*.py' "$ANY_WRAPPER_RE" "$DEPLOY_ROOT" 2>/dev/null | grep -v '_wrapper_bridge.py' | grep -v '_bootstrap.py' | grep -v '_code_bridge.py' || true)"
+fi
+if [ -n "$MATCHES" ]; then
+  echo "$MATCHES"
+  echo "FAIL: praisonai_deploy imports the praisonai wrapper"
+  exit 1
+fi
+echo "deploy wrapper import gate ok"
+
+echo "== C14 praisonai_deploy module-level praisonai_code import gate =="
+if command -v rg >/dev/null 2>&1; then
+  MATCHES="$(rg -n "$ANY_CODE_RE" "$DEPLOY_ROOT" --glob '*.py' 2>/dev/null | grep -v '_code_bridge.py' | grep -v '_plugin_registry.py' || true)"
+else
+  MATCHES="$(grep -rEn --include='*.py' "$ANY_CODE_RE" "$DEPLOY_ROOT" 2>/dev/null | grep -v '_code_bridge.py' | grep -v '_plugin_registry.py' || true)"
+fi
+if [ -n "$MATCHES" ]; then
+  echo "$MATCHES"
+  echo "FAIL: module-level praisonai_code import in praisonai_deploy"
+  exit 1
+fi
+echo "deploy code import gate ok"
+
+echo "== C14 praisonai-code hot-path gate (no praisonai_deploy at module level) =="
+for f in \
+  "$CODE_ROOT/cli/main.py" \
+  "$CODE_ROOT/cli/app.py" \
+  "$CODE_ROOT/cli/commands/run.py" \
+  "$CODE_ROOT/cli/commands/chat.py" \
+  "$CODE_ROOT/cli/commands/code.py"
+do
+  if [ -f "$f" ] && head -n 80 "$f" | grep -E "$ANY_DEPLOY_RE" 2>/dev/null; then
+    echo "FAIL: module-level praisonai_deploy import in code hot path $f"
+    exit 1
+  fi
+done
+echo "code hot-path gate ok"
+
+echo "C14 import gates passed"
@@ -0,0 +1,60 @@
+#!/usr/bin/env bash
+# Lint and template-render all Helm charts under package infra/ trees.
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+
+if ! command -v helm >/dev/null 2>&1; then
+  echo "FAIL: helm CLI not found (install via https://helm.sh/docs/intro/install/)"
+  exit 1
+fi
+
+HELM_ROOTS=(
+  "$ROOT/src/praisonai-bot/infra/helm"
+  "$ROOT/src/praisonai-deploy/infra/helm"
+)
+
+charts=()
+for helm_root in "${HELM_ROOTS[@]}"; do
+  if [ ! -d "$helm_root" ]; then
+    continue
+  fi
+  shopt -s nullglob
+  for chart in "$helm_root"/*/; do
+    if [ -f "${chart}Chart.yaml" ]; then
+      charts+=("$chart")
+    fi
+  done
+  shopt -u nullglob
+done
+
+if [ ${#charts[@]} -eq 0 ]; then
+  echo "No charts found under package infra/helm trees"
+  exit 1
+fi
+
+for chart in "${charts[@]}"; do
+  name="$(basename "$chart")"
+  echo "== helm lint: $name =="
+  helm lint "$chart"
+
+  echo "== helm template: $name =="
+  case "$name" in
+    praisonai-gateway)
+      helm template "ci-smoke-$name" "$chart" \
+        --set auth.existingSecret=ci-smoke-auth \
+        >/dev/null
+      ;;
+    praisonai-agents-api)
+      helm template "ci-smoke-$name" "$chart" \
+        --set auth.existingSecret=ci-smoke-auth \
+        --set postgres.auth.existingSecret=ci-smoke-postgres \
+        >/dev/null
+      ;;
+    *)
+      helm template "ci-smoke-$name" "$chart" >/dev/null
+      ;;
+  esac
+done
+
+echo "Helm chart gates passed (${#charts[@]} chart(s))"
@@ -140,7 +140,7 @@ The **agentic terminal CLI** (`run`, `chat`, `code`, warm runtime, CLI backends,

 **Monorepo bootstrap:** `praisonai._bootstrap.ensure_praisonai_code()` adds sibling `src/praisonai-code` to `sys.path` so `PYTHONPATH=src/praisonai-agents:src/praisonai` works without an explicit code entry.

-**Install order (CI and local dev):** `praisonai-agents` → `praisonai-code` → `praisonai` (see `.github/actions/install-monorepo-packages`).
+**Install order (CI and local dev):** `praisonai-agents` → `praisonai-code` → `praisonai-bot` → `praisonai-train` → `praisonai-browser` → `praisonai-mcp` → `praisonai-sandbox` → `praisonai-deploy` → `praisonai` (see `.github/actions/install-monorepo-packages`).

 **Invocation paths that must remain valid:**

@@ -18,76 +18,76 @@ This report compares **Python SDK feature categories** against **Python document
 | Category | Features | Docs | Lines |
 |----------|----------|------|-------|
 | ✅ AGUI | 1 | 2 | 420 |
-| ✅ Agent | 21 | 45 | 14186 |
+| ✅ Agent | 22 | 49 | 15473 |
 | ✅ Agent-to-Agent (A2A) | 1 | 7 | 2965 |
-| ✅ Agent-to-User (A2U) | 1 | 3 | 585 |
-| ✅ Approval | 1 | 5 | 2286 |
+| ✅ Agent-to-User (A2U) | 1 | 3 | 684 |
+| ✅ Approval | 1 | 5 | 2500 |
 | ✅ Audio | 2 | 12 | 1000 |
-| ✅ Auto Generation | 5 | 10 | 2868 |
-| ✅ Autonomy | 3 | 7 | 2707 |
-| ✅ Bots | 7 | 28 | 11301 |
+| ✅ Auto Generation | 5 | 10 | 3005 |
+| ✅ Autonomy | 3 | 7 | 2736 |
+| ✅ Bots | 7 | 31 | 13274 |
 | ✅ Budget | 1 | 1 | 287 |
-| ✅ CLI | 5 | 119 | 33852 |
+| ✅ CLI | 5 | 121 | 35658 |
 | ✅ Chunking | 2 | 2 | 385 |
 | ✅ Citations | 2 | 1 | 202 |
-| ✅ Code Execution | 2 | 13 | 3970 |
+| ✅ Code Execution | 2 | 14 | 4548 |
 | ✅ Conditions | 1 | 3 | 1179 |
-| ✅ Configuration | 3 | 7 | 2772 |
-| ✅ Context Management | 16 | 34 | 13204 |
+| ✅ Configuration | 3 | 8 | 3047 |
+| ✅ Context Management | 16 | 34 | 13388 |
 | ✅ Deep Research | 8 | 2 | 587 |
 | ✅ Display | 6 | 3 | 741 |
 | ✅ Embeddings | 6 | 23 | 2049 |
-| ✅ Evaluation | 1 | 7 | 2902 |
+| ✅ Evaluation | 1 | 7 | 2905 |
 | ✅ Events | 1 | 2 | 749 |
-| ✅ Execution | 3 | 4 | 1528 |
-| ✅ Failover | 2 | 1 | 400 |
-| ✅ Files | 2 | 6 | 1964 |
-| ✅ Flow | 1 | 3 | 777 |
-| ✅ Gateway | 7 | 54 | 19347 |
-| ✅ Guardrails | 4 | 4 | 1673 |
-| ✅ Handoffs | 11 | 6 | 2454 |
-| ✅ Hooks | 2 | 9 | 4124 |
+| ✅ Execution | 3 | 4 | 1560 |
+| ✅ Failover | 2 | 1 | 432 |
+| ✅ Files | 2 | 7 | 2273 |
+| ✅ Flow | 1 | 3 | 788 |
+| ✅ Gateway | 7 | 66 | 24288 |
+| ✅ Guardrails | 4 | 4 | 1833 |
+| ✅ Handoffs | 11 | 6 | 2563 |
+| ✅ Hooks | 2 | 9 | 4281 |
 | ✅ Image | 1 | 11 | 1255 |
-| ✅ Knowledge | 4 | 13 | 4160 |
-| ✅ LLM | 3 | 14 | 4830 |
-| ✅ Loops | 4 | 4 | 1202 |
-| ✅ MCP | 1 | 58 | 13322 |
-| ✅ Memory | 6 | 17 | 6635 |
+| ✅ Knowledge | 4 | 13 | 4233 |
+| ✅ LLM | 3 | 14 | 4955 |
+| ✅ Loops | 4 | 5 | 1422 |
+| ✅ MCP | 1 | 60 | 13724 |
+| ✅ Memory | 6 | 17 | 6766 |
 | ✅ OCR | 2 | 1 | 237 |
-| ✅ Observability | 2 | 23 | 2779 |
+| ✅ Observability | 2 | 23 | 2800 |
 | ✅ Optimizer | 1 | 2 | 792 |
 | ✅ Output | 3 | 5 | 1158 |
 | ✅ Parallel Execution | 3 | 2 | 497 |
-| ✅ Planning | 6 | 6 | 1545 |
-| ✅ Plugins | 8 | 3 | 1900 |
-| ✅ Prompts | 2 | 9 | 1910 |
-| ✅ Providers | 1 | 55 | 7502 |
+| ✅ Planning | 6 | 6 | 1549 |
+| ✅ Plugins | 8 | 4 | 2703 |
+| ✅ Prompts | 2 | 9 | 1965 |
+| ✅ Providers | 1 | 56 | 7723 |
 | ✅ Query | 1 | 2 | 736 |
 | ✅ RAG | 5 | 15 | 2936 |
 | ✅ Realtime | 2 | 5 | 668 |
 | ✅ Reflection | 3 | 3 | 680 |
 | ✅ Retrieval | 2 | 5 | 1044 |
 | ✅ Routing | 1 | 2 | 430 |
-| ✅ Sandbox | 5 | 6 | 2700 |
-| ✅ Security | 1 | 3 | 2966 |
-| ✅ Sessions | 4 | 13 | 5286 |
-| ✅ Skills | 6 | 13 | 4946 |
-| ✅ Tasks | 2 | 6 | 2743 |
+| ✅ Sandbox | 5 | 6 | 2806 |
+| ✅ Security | 1 | 3 | 3135 |
+| ✅ Sessions | 4 | 17 | 6960 |
+| ✅ Skills | 6 | 15 | 5638 |
+| ✅ Tasks | 2 | 6 | 2819 |
 | ✅ Telemetry | 1 | 2 | 604 |
-| ✅ Templates | 1 | 8 | 1657 |
-| ✅ Tools | 12 | 133 | 37869 |
+| ✅ Templates | 1 | 8 | 1663 |
+| ✅ Tools | 12 | 138 | 40206 |
 | ✅ Tracing | 3 | 2 | 139 |
-| ✅ Vector Store | 1 | 12 | 1193 |
+| ✅ Vector Store | 1 | 12 | 1207 |
 | ✅ Video | 2 | 6 | 649 |
 | ✅ Vision | 2 | 1 | 329 |
-| ✅ Web | 3 | 8 | 2055 |
-| ✅ Workflows | 5 | 16 | 6546 |
+| ✅ Web | 3 | 9 | 2467 |
+| ✅ Workflows | 5 | 16 | 6589 |

 ## Documentation Without Features

 These docs exist but don't match any implemented feature category:

- ℹ️ Database (40 docs, 6184 lines)
+- ℹ️ Database (42 docs, 6703 lines)
 - ℹ️ Documents (1 docs, 787 lines)

 ---
@@ -258,6 +258,7 @@ _LAZY_IMPORTS = {
    
    # Agent classes
    'Agent': ('praisonaiagents.agent.agent', 'Agent'),
+    'RunOutcome': ('praisonaiagents.agent.run_outcome', 'RunOutcome'),
    'RetryBackoffConfig': ('praisonaiagents.agent.retry_utils', 'RetryBackoffConfig'),
    'BudgetExceededError': ('praisonaiagents.errors', 'BudgetExceededError'),
    
@@ -303,9 +304,10 @@ _LAZY_IMPORTS = {
    'CodeAgent': ('praisonaiagents.agent.code_agent', 'CodeAgent'),
    'CodeConfig': ('praisonaiagents.agent.code_agent', 'CodeConfig'),
    
-    # AgentTeam (primary) / AgentManager (alias)
+    # AgentTeam (primary) / AgentManager, PraisonAIAgents (aliases)
    'AgentTeam': ('praisonaiagents.agents.agents', 'AgentTeam'),
    'AgentManager': ('praisonaiagents.agents.agents', 'AgentManager'),  # Silent alias
+    'PraisonAIAgents': ('praisonaiagents.agents.agents', 'PraisonAIAgents'),  # Silent alias (pre-1.0 name)
    # Note: 'Agents' is handled by _custom_handler for deprecation warning
    'Task': ('praisonaiagents.task.task', 'Task'),
    'AutoAgents': ('praisonaiagents.agents.autoagents', 'AutoAgents'),
@@ -838,9 +840,11 @@ __all__ = [
    
    # Core classes - the essentials
    'Agent',
+    'RunOutcome',
    'RetryBackoffConfig',
    'AgentTeam',  # Primary class for multi-agent coordination (v1.0+)
    'AgentManager',  # Silent alias for AgentTeam
+    'PraisonAIAgents',  # Silent alias for AgentTeam (pre-1.0 name)
    'Agents',  # Deprecated alias for AgentTeam (emits warning)
    'Task',
    
@@ -4,7 +4,6 @@ This module consolidates all logging configuration in one place to avoid duplica
 """

 import os
-import json
 import logging
 from typing import Any, Dict, List, Optional, Union

@@ -196,6 +195,9 @@ class StructuredFormatter(logging.Formatter):
            extra = {k: v for k, v in record.extra_data.items() if k not in self._STANDARD_FIELDS}
            log_data.update(extra)

+        # Deferred: json is only needed for opt-in structured logging
+        import json
+
        return json.dumps(log_data)


@@ -37,6 +37,15 @@ def __getattr__(name):
        from .interrupt import InterruptController
        _lazy_cache[name] = InterruptController
        return InterruptController
+    if name in ('RunOutcome', 'TerminalReason'):
+        from . import run_outcome as _run_outcome_module
+        value = getattr(_run_outcome_module, name)
+        _lazy_cache[name] = value
+        return value
+    if name == 'prompt_prefix_signature':
+        from .prompt_cache import prompt_prefix_signature
+        _lazy_cache[name] = prompt_prefix_signature
+        return prompt_prefix_signature
    
    # Specialized agents - lazy loaded (import rich)
    if name == 'ImageAgent':
@@ -215,6 +224,9 @@ __all__ = [
    'Heartbeat',
    'HeartbeatConfig',
    'InterruptController',
+    'RunOutcome',
+    'TerminalReason',
+    'prompt_prefix_signature',
    'ImageAgent',
    'VideoAgent',
    'VideoConfig',
@@ -20,7 +20,7 @@ from .async_memory_mixin import AsyncMemoryMixin
 from .tool_execution import ToolExecutionMixin, BackoffPolicy
 from .chat_handler import ChatHandlerMixin
 from .session_manager import SessionManagerMixin
-from .async_safety import AsyncSafeState
+from .async_safety import AsyncSafeState, DualLock
 # NOTE: UnifiedExecutionMixin is deprecated and unused by any production path
 # (Issue #2644). It is kept in the MRO for backward compatibility during the
 # deprecation cycle and will be removed afterwards.
@@ -859,8 +859,6 @@ class Agent(GoalLoopMixin, SteeringMixin, SandboxMixin, SkillReviewMixin, Unifie
        planning_tools = None
        planning_reasoning = False
        policy = None
-        background = None
-        checkpoints = None
        output_style = None
        thinking_budget = None
        skills_dirs = None
@@ -1655,7 +1653,14 @@ class Agent(GoalLoopMixin, SteeringMixin, SandboxMixin, SkillReviewMixin, Unifie
            else:
                llm = model  # model= takes precedence
        
-        # Store rate limiter (optional, zero overhead when None)
+        # Store rate limiter (optional, zero overhead when None).
+        # Auto-build a RateLimiter from max_rpm when no explicit limiter is
+        # provided so ExecutionConfig(max_rpm=N) actually throttles requests.
+        if max_rpm is not None and max_rpm <= 0:
+            raise ValueError(f"max_rpm must be a positive int, got {max_rpm!r}")
+        if rate_limiter is None and max_rpm is not None:
+            from praisonaiagents.llm.rate_limiter import RateLimiter
+            rate_limiter = RateLimiter(requests_per_minute=max_rpm)
        self._rate_limiter = rate_limiter
        
        # Store OpenAI client parameters for lazy initialization (kept separate)
@@ -1977,21 +1982,27 @@ Your Goal: {self.goal}
        # None = normal rule flow. Consulted at tool-call approval time.
        self._permission_mode = None
        if isinstance(approval, str) and approval not in ('True', 'False'):
-            # Permission preset: "safe", "read_only", "full"
+            # One string entry point for "how much the agent may do":
+            #   • deny-set presets — "safe"/"read_only"/"full"/"off"/"default"
+            #   • PermissionMode presets — "plan"/"bypass"/"accept_edits"/
+            #     "dont_ask" (+ aliases like "yolo", "auto_edit", "reject").
+            # Deny-set presets are matched first so their exact behaviour is
+            # unchanged; anything else falls through to the canonical
+            # PermissionMode resolver, so all spellings share one model.
            from ..approval.registry import PERMISSION_PRESETS
-            preset_deny = PERMISSION_PRESETS.get(approval)
+            preset_deny = PERMISSION_PRESETS.get(approval.strip().lower())
+            self._approval_backend = None
+            self._approve_all_tools = False
+            self._approval_timeout = 0
+            self._approval_permissions = None
            if preset_deny is not None:
                self._perm_deny = preset_deny
-                self._approval_backend = None
-                self._approve_all_tools = False
-                self._approval_timeout = 0
-                self._approval_permissions = None
            else:
-                # Unknown string — treat as no approval
-                self._approval_backend = None
-                self._approve_all_tools = False
-                self._approval_timeout = 0
-                self._approval_permissions = None
+                # Not a deny-set preset — try the canonical PermissionMode
+                # presets (plan/bypass/accept_edits/dont_ask + aliases).
+                from ..permissions.rules import PermissionMode
+                self._permission_mode = PermissionMode.resolve(approval)
+                # Unknown string with no mode → treat as no approval.
        elif approval is True:
            from ..approval.backends import AutoApproveBackend
            self._approval_backend = AutoApproveBackend()
@@ -2116,6 +2127,12 @@ Your Goal: {self.goal}
        
        # Store tool retry policy for tool execution with exponential backoff
        self._tool_retry_policy = _tool_config.retry_policy if _tool_config else None
+
+        # Whether undeclared tool names may resolve via the process-global @tool
+        # registry. Default False keeps the agent scoped to its own tools=[...].
+        self._allow_global_tools = (
+            _tool_config.allow_global_tools if _tool_config else False
+        )
        
        # Retry configuration with jittered exponential backoff.
        # Default (retry is None) applies RetryBackoffConfig() so the native
@@ -2224,7 +2241,10 @@ Your Goal: {self.goal}
        # Per-turn tool-name buffer feeding the self-improve review policy.
        # Populated in _execute_tool_with_context, reset each chat turn, and
        # read by _trigger_after_agent_hook when tools_used is not passed.
+        # Guarded by a DualLock (like chat_history) so concurrent chat()/achat()
+        # turns on the same Agent instance don't corrupt each other's buffer.
        self._turn_tools_used = []
+        self._turn_tools_lock = DualLock()

        # Database persistence (lazy - no imports until used)
        self._db = db
@@ -2248,8 +2268,6 @@ Your Goal: {self.goal}
        # Agent-centric feature instances (lazy loaded for zero performance impact)
        self._auto_memory = auto_memory
        self._policy = policy
-        self._background = background
-        self._checkpoints = checkpoints
        self._output_style = output_style
        self._thinking_budget = thinking_budget
        
@@ -2523,24 +2541,6 @@ Your Goal: {self.goal}
    def policy(self, value: Optional[Any]) -> None:
        self._policy = value

-    @property
-    def background(self) -> Optional[bool]:
-        """BackgroundRunner instance for async task execution."""
-        return self._background
-    
-    @background.setter
-    def background(self, value: Optional[bool]) -> None:
-        self._background = value
-
-    @property
-    def checkpoints(self) -> Optional[bool]:
-        """CheckpointService instance for file-level undo/restore."""
-        return self._checkpoints
-    
-    @checkpoints.setter
-    def checkpoints(self, value: Optional[bool]) -> None:
-        self._checkpoints = value
-
    @property
    def output_style(self) -> Optional[str]:
        """OutputStyle instance for response formatting."""
@@ -2703,16 +2703,7 @@ Your Goal: {self.goal}
                from ..context.models import ContextConfig as _ContextConfig
                if isinstance(self._context_param, _ContextConfig):
                    # Build ManagerConfig from ContextConfig fields
-                    manager_config = ManagerConfig(
-                        auto_compact=self._context_param.auto_compact,
-                        compact_threshold=self._context_param.compact_threshold,
-                        strategy=self._context_param.strategy,
-                        output_reserve=self._context_param.output_reserve,
-                        default_tool_output_max=self._context_param.tool_output_max,  # Map field name
-                        protected_tools=list(self._context_param.protected_tools),
-                        keep_recent_turns=self._context_param.keep_recent_turns,
-                        monitor_enabled=self._context_param.monitor.enabled if self._context_param.monitor else False,
-                    )
+                    manager_config = self._manager_config_from_context_config(self._context_param)
                    # Check if llm_summarize is enabled in ContextConfig
                    llm_summarize_enabled = getattr(self._context_param, 'llm_summarize', False)
                    if llm_summarize_enabled:
@@ -2741,16 +2732,7 @@ Your Goal: {self.goal}
                try:
                    from ..context.models import ContextConfig as _ContextConfig
                    context_config = _ContextConfig(**preset_config)
-                    manager_config = ManagerConfig(
-                        auto_compact=context_config.auto_compact,
-                        compact_threshold=context_config.compact_threshold,
-                        strategy=context_config.strategy,
-                        output_reserve=context_config.output_reserve,
-                        default_tool_output_max=context_config.tool_output_max,
-                        protected_tools=list(context_config.protected_tools),
-                        keep_recent_turns=context_config.keep_recent_turns,
-                        monitor_enabled=context_config.monitor.enabled if context_config.monitor else False,
-                    )
+                    manager_config = self._manager_config_from_context_config(context_config)
                    self._context_manager = ContextManager(
                        model=self.llm if isinstance(self.llm, str) else "gpt-4o-mini",
                        config=manager_config,
@@ -2769,16 +2751,7 @@ Your Goal: {self.goal}
            try:
                from ..context.models import ContextConfig as _ContextConfig
                context_config = _ContextConfig(**self._context_param)
-                manager_config = ManagerConfig(
-                    auto_compact=context_config.auto_compact,
-                    compact_threshold=context_config.compact_threshold,
-                    strategy=context_config.strategy,
-                    output_reserve=context_config.output_reserve,
-                    default_tool_output_max=context_config.tool_output_max,
-                    protected_tools=list(context_config.protected_tools),
-                    keep_recent_turns=context_config.keep_recent_turns,
-                    monitor_enabled=context_config.monitor.enabled if context_config.monitor else False,
-                )
+                manager_config = self._manager_config_from_context_config(context_config)
                llm_summarize_enabled = self._context_param.get('llm_summarize', False)
                self._context_manager = ContextManager(
                    model=self.llm if isinstance(self.llm, str) else "gpt-4o-mini",
@@ -2803,6 +2776,20 @@ Your Goal: {self.goal}
        self._context_manager = value
        self._context_manager_initialized = True

+    def _manager_config_from_context_config(self, cc: Any) -> Any:
+        """Build a ManagerConfig from a ContextConfig (single source of truth)."""
+        from ..context import ManagerConfig
+        return ManagerConfig(
+            auto_compact=cc.auto_compact,
+            compact_threshold=cc.compact_threshold,
+            strategy=cc.strategy,
+            output_reserve=cc.output_reserve,
+            default_tool_output_max=cc.tool_output_max,  # Map field name
+            protected_tools=list(cc.protected_tools),
+            keep_recent_turns=cc.keep_recent_turns,
+            monitor_enabled=cc.monitor.enabled if cc.monitor else False,
+        )
+
    def _create_llm_summarize_fn(self) -> Optional[Callable]:
        """
        Create an LLM summarization function using the agent's LLM.
@@ -2830,9 +2817,19 @@ Conversation:

 Summary:"""
                
-                # Use agent's LLM to generate summary
+                # Use agent's LLM to generate summary. Route this internal,
+                # non-user-facing call through the configured auxiliary
+                # ``small_model`` when set; otherwise fall back to the primary
+                # model (unchanged behaviour).
                client = _get_llm_functions()['get_openai_client'](self.llm, self.base_url, self.api_key)
-                model_name = self.llm if isinstance(self.llm, str) else "gpt-4o-mini"
+                primary_model = self.llm if isinstance(self.llm, str) else None
+                try:
+                    from ..config.loader import get_small_model
+                    model_name = get_small_model(
+                        primary_model=primary_model, fallback="gpt-4o-mini"
+                    ) or "gpt-4o-mini"
+                except Exception:
+                    model_name = primary_model or "gpt-4o-mini"
                
                response = client.chat.completions.create(
                    model=model_name,
@@ -3192,7 +3189,44 @@ Summary:"""
    # ================================================================
    # Filesystem tracking convenience methods (powered by FileSnapshot)
    # ================================================================
-    
+
+    def set_snapshot_root(self, project_path: str) -> bool:
+        """Root filesystem change-tracking at ``project_path``.
+
+        Bots/gateway resolve file tools against a per-chat ``Workspace`` and
+        attach it *after* construction, but the FileSnapshot backing
+        :meth:`undo`/:meth:`redo`/:meth:`diff` was created at ``__init__`` time
+        rooted at ``os.getcwd()``. Without this, ``/undo`` tracks the wrong
+        directory (never where the tools actually wrote). Call this once after
+        the workspace is known so change tracking follows the tools.
+
+        Rooting at a new directory clears the undo/redo stacks (they belong to
+        the previous root). A no-op when the root is unchanged. Returns ``True``
+        when a snapshot manager is rooted at ``project_path``.
+        """
+        import os
+        new_root = os.path.abspath(str(project_path))
+        current = self._file_snapshot
+        if current is not None and getattr(current, "project_path", None) == new_root:
+            return True
+        try:
+            from ..snapshot import FileSnapshot
+            snapshot_dir = None
+            cfg = getattr(self, "autonomy_config", None)
+            if isinstance(cfg, dict):
+                snapshot_dir = cfg.get("snapshot_dir")
+            self._file_snapshot = FileSnapshot(
+                project_path=new_root,
+                snapshot_dir=snapshot_dir,
+            )
+            with self._snapshot_lock:
+                self._snapshot_stack = []
+                self._redo_stack = []
+            return True
+        except Exception as e:  # pragma: no cover - git may be unavailable
+            logger.debug(f"Re-rooting FileSnapshot failed: {e}")
+            return False
+
    def undo(self) -> bool:
        """Undo the last set of file changes.
        
@@ -4923,8 +4957,20 @@ Summary:"""
            self._memory_instance = None
            return
        
-        # Determine user_id
-        mem_user_id = user_id or getattr(self, 'user_id', None) or "default"
+        # Determine user_id. A shared constant default (e.g. "praison") would
+        # silently merge different sessions'/users' private memory onto the same
+        # on-disk path. When memory is enabled and no explicit user_id was given,
+        # fall back to a per-instance, non-shared id so agents are isolated by
+        # default. Pass user_id=... explicitly to persist/share memory across runs.
+        mem_user_id = user_id
+        if not mem_user_id:
+            import uuid
+            mem_user_id = f"agent-{uuid.uuid4().hex[:12]}"
+            logging.warning(
+                "Agent memory enabled without an explicit user_id; using an "
+                "auto-generated, non-shared id (%s). Pass user_id=... explicitly "
+                "to persist/share memory across runs.", mem_user_id,
+            )
        
        if memory is True or memory == "file":
            # Use FileMemory (zero dependencies)
@@ -5566,6 +5612,16 @@ Answer:"""
            # Prefer the configured LLM instance (with api_key/base_url/client
            # overrides) over the bare model-name string in self.llm.
            llm = getattr(self, 'llm_instance', None) or getattr(self, 'llm', None)
+            # Guardrail validation is an internal, non-user-facing LLM call.
+            # When it would fall back to the bare primary model-name string
+            # (no explicit LLM instance), route through the auxiliary
+            # ``small_model`` (unset -> primary model, i.e. unchanged behaviour).
+            if isinstance(llm, str):
+                try:
+                    from ..config.loader import get_small_model
+                    llm = get_small_model(primary_model=llm, fallback=llm) or llm
+                except Exception:
+                    pass
            self._guardrail_fn = LLMGuardrail(description=self.guardrail, llm=llm)
        else:
            raise ValueError("Agent guardrail must be either a callable or a string description")
@@ -6370,10 +6426,14 @@ Answer:"""
        """Clean up global server registry entries for this agent."""
        if getattr(self, '_agent_id', None) is None:
            return  # No ID generated, nothing registered
-            
+
        try:
-            _get_default_server_registry().cleanup_agent_registrations(self._agent_id)
-                    
+            # Tear down the routes launch() actually registered (module-level
+            # state in execution_mixin.py). ServerRegistry above is a separate,
+            # unpopulated structure and cleaning it up is a no-op.
+            from .execution_mixin import cleanup_launch_registration
+            cleanup_launch_registration(self._agent_id)
+
        except Exception as e:
            import sys
            if sys.meta_path is not None:
@@ -7,7 +7,6 @@ async capabilities following the AsyncMemoryProtocol.
 """

 import asyncio
-import logging
 from typing import List, Dict, Any, Optional, Union
 from praisonaiagents._logging import get_logger
 from ..memory.protocols import AsyncMemoryProtocol
@@ -34,7 +34,6 @@ Usage:
 from dataclasses import dataclass, field
 from typing import Optional, Dict, Any, List, Set
 from enum import Enum
-import logging
 from praisonaiagents._logging import get_logger

 logger = get_logger(__name__)
@@ -625,11 +625,26 @@ Your Goal: {self.goal}"""
                    formatted_tools.extend(openai_tools)
                elif openai_tools is not None:
                    formatted_tools.append(openai_tools)
-            # Handle callable functions
-            elif callable(tool):
-                tool_def = self._generate_tool_definition(tool.__name__)
+            # Handle BaseTool-style instances (ClarifyTool, etc.)
+            elif getattr(tool, "name", None) and hasattr(tool, "run"):
+                tool_def = self._generate_tool_definition(tool.name)
                if tool_def:
                    formatted_tools.append(tool_def)
+                else:
+                    logging.warning(
+                        "Could not generate definition for tool: %s", tool.name
+                    )
+            # Handle callable functions
+            elif callable(tool):
+                fname = getattr(tool, "name", None) or getattr(tool, "__name__", None)
+                if not fname:
+                    logging.warning("Tool %r not recognized (no name)", tool)
+                    continue
+                tool_def = self._generate_tool_definition(fname)
+                if tool_def:
+                    formatted_tools.append(tool_def)
+                else:
+                    logging.warning(f"Could not generate definition for tool: {fname}")
            else:
                logging.warning(f"Tool {tool} not recognized")
        
@@ -1290,6 +1305,104 @@ Your Goal: {self.goal}"""
            return None
        return self.fallback_models[fallback_index]

+    def _emit_model_fallback(self, from_model, to_model, reason_category, fallback_index,
+                             stream_callback=None):
+        """Surface a mid-turn model fallback as an observable state transition.
+
+        Fired at the exact point the recovery loop swaps the primary model for
+        the next entry in ``fallback_models``. Emits a ``MODEL_FALLBACK`` hook
+        (so plugins/gateways can react — notice, alert, metrics) and, when a
+        stream callback is active, a ``StreamEventType.MODEL_FALLBACK`` event so
+        the streaming/draft layer can mark the switch. Only the failure class is
+        exposed; provider internals stay redacted. Fully guarded and a cheap
+        no-op when nothing is subscribed — preserving today's behaviour plus the
+        existing log line (Issue #3820).
+        """
+        try:
+            from ..hooks.types import HookEvent
+
+            runner = getattr(self, '_hook_runner', None)
+            if runner is not None and runner.registry.has_hooks(HookEvent.MODEL_FALLBACK):
+                runner.execute_sync(
+                    HookEvent.MODEL_FALLBACK,
+                    self._build_model_fallback_input(
+                        from_model, to_model, reason_category, fallback_index, HookEvent
+                    ),
+                )
+        except Exception:  # observability must never break the fallback path
+            logging.debug("MODEL_FALLBACK hook failed", exc_info=True)
+
+        self._emit_model_fallback_stream(
+            from_model, to_model, reason_category, fallback_index, stream_callback
+        )
+
+    async def _aemit_model_fallback(self, from_model, to_model, reason_category, fallback_index,
+                                    stream_callback=None):
+        """Async variant of :meth:`_emit_model_fallback` for the async recovery path.
+
+        Awaits the hook runner in the active event loop (``execute_sync`` would
+        raise inside a running loop, silently dropping ``MODEL_FALLBACK`` hooks).
+        Same guarantees: cheap no-op when nothing is subscribed and never raises
+        into the fallback path.
+        """
+        try:
+            from ..hooks.types import HookEvent
+
+            runner = getattr(self, '_hook_runner', None)
+            if runner is not None and runner.registry.has_hooks(HookEvent.MODEL_FALLBACK):
+                await runner.execute(
+                    HookEvent.MODEL_FALLBACK,
+                    self._build_model_fallback_input(
+                        from_model, to_model, reason_category, fallback_index, HookEvent
+                    ),
+                )
+        except Exception:  # observability must never break the fallback path
+            logging.debug("MODEL_FALLBACK hook failed", exc_info=True)
+
+        self._emit_model_fallback_stream(
+            from_model, to_model, reason_category, fallback_index, stream_callback
+        )
+
+    def _build_model_fallback_input(self, from_model, to_model, reason_category,
+                                    fallback_index, HookEvent):
+        """Build the typed ``ModelFallbackInput`` (only the failure class is exposed)."""
+        from ..hooks.events import ModelFallbackInput
+
+        return ModelFallbackInput(
+            session_id=getattr(self, '_session_id', 'default'),
+            cwd=os.getcwd(),
+            event_name=HookEvent.MODEL_FALLBACK.value,
+            timestamp=str(time.time()),
+            agent_name=getattr(self, 'name', None),
+            from_model=str(from_model),
+            to_model=str(to_model),
+            reason_category=str(reason_category or ""),
+            fallback_index=fallback_index,
+        )
+
+    def _emit_model_fallback_stream(self, from_model, to_model, reason_category,
+                                    fallback_index, stream_callback):
+        """Emit the ``StreamEventType.MODEL_FALLBACK`` event when a callback is active."""
+        if stream_callback is None:
+            return
+        try:
+            from ..streaming.events import StreamEvent, StreamEventType
+
+            stream_callback(StreamEvent(
+                type=StreamEventType.MODEL_FALLBACK,
+                metadata={
+                    "from_model": str(from_model),
+                    "to_model": str(to_model),
+                    "reason_category": str(reason_category or ""),
+                    "fallback_index": fallback_index,
+                },
+                agent_id=getattr(self, 'name', None),
+                session_id=getattr(self, '_session_id', None),
+                run_id=getattr(self, '_current_run_id', None),
+            ))
+        except Exception:
+            logging.debug("MODEL_FALLBACK stream event failed", exc_info=True)
+
    def _max_retry_depth(self) -> int:
        """Maximum LLM retry depth honoured by the recovery loop.

@@ -1330,34 +1443,36 @@ Your Goal: {self.goal}"""
        self._apply_context_compaction(messages, _HookEvent)

        # Trigger BEFORE_LLM hook
+        # Only build the input if a BEFORE_LLM hook is actually registered
        from ..hooks import HookEvent, BeforeLLMInput
-        before_llm_input = BeforeLLMInput(
-            session_id=getattr(self, '_session_id', 'default'),
-            cwd=os.getcwd(),
-            event_name=HookEvent.BEFORE_LLM,
-            timestamp=str(time.time()),
-            agent_name=self.name,
-            messages=messages,
-            model=self.llm if isinstance(self.llm, str) else str(self.llm),
-            temperature=temperature
-        )
-        _before_llm_results = self._hook_runner.execute_sync(HookEvent.BEFORE_LLM, before_llm_input)
-        # Honour a blocking BEFORE_LLM hook/plugin (POLICY/GUARDRAIL) by
-        # refusing to dispatch the request, mirroring how BEFORE_TOOL/BEFORE_AGENT
-        # enforce blocks. Without this, a plugin that returns PluginDecision.deny()
-        # (or raises GuardrailBlocked) would fail open and still hit the model.
-        if self._hook_runner.is_blocked(_before_llm_results):
-            _block_reason = next(
-                (getattr(r.output, "reason", None) for r in _before_llm_results
-                 if r.output and getattr(r.output, "is_denied", lambda: False)()),
-                None,
-            ) or "Blocked by hook"
-            logging.warning(f"Agent {self.name} LLM request blocked by BEFORE_LLM hook: {_block_reason}")
-            return f"[LLM request blocked by hook: {_block_reason}]"
-        # C7 - honour any BEFORE_LLM hook that mutated the message stream
-        # (e.g. PII redactor). The runner applies modified_input in-place on
-        # before_llm_input.messages; adopt that value for the actual LLM call.
-        messages = before_llm_input.messages
+        if self._hook_runner.registry.has_hooks(HookEvent.BEFORE_LLM):
+            before_llm_input = BeforeLLMInput(
+                session_id=getattr(self, '_session_id', 'default'),
+                cwd=os.getcwd(),
+                event_name=HookEvent.BEFORE_LLM,
+                timestamp=str(time.time()),
+                agent_name=self.name,
+                messages=messages,
+                model=self.llm if isinstance(self.llm, str) else str(self.llm),
+                temperature=temperature
+            )
+            _before_llm_results = self._hook_runner.execute_sync(HookEvent.BEFORE_LLM, before_llm_input)
+            # Honour a blocking BEFORE_LLM hook/plugin (POLICY/GUARDRAIL) by
+            # refusing to dispatch the request, mirroring how BEFORE_TOOL/BEFORE_AGENT
+            # enforce blocks. Without this, a plugin that returns PluginDecision.deny()
+            # (or raises GuardrailBlocked) would fail open and still hit the model.
+            if self._hook_runner.is_blocked(_before_llm_results):
+                _block_reason = next(
+                    (getattr(r.output, "reason", None) for r in _before_llm_results
+                     if r.output and getattr(r.output, "is_denied", lambda: False)()),
+                    None,
+                ) or "Blocked by hook"
+                logging.warning(f"Agent {self.name} LLM request blocked by BEFORE_LLM hook: {_block_reason}")
+                return f"[LLM request blocked by hook: {_block_reason}]"
+            # C7 - honour any BEFORE_LLM hook that mutated the message stream
+            # (e.g. PII redactor). The runner applies modified_input in-place on
+            # before_llm_input.messages; adopt that value for the actual LLM call.
+            messages = before_llm_input.messages

        # Pre-call budget guard (zero overhead when _max_budget is None).
        # Estimate this call's minimum cost from the known input size plus the
@@ -1511,19 +1626,21 @@ Your Goal: {self.goal}"""
                    self._on_budget_exceeded(current_cost, self._max_budget)
            
            # Trigger AFTER_LLM hook
+            # Only build the input if an AFTER_LLM hook is actually registered
            from ..hooks import HookEvent, AfterLLMInput
-            after_llm_input = AfterLLMInput(
-                session_id=getattr(self, '_session_id', 'default'),
-                cwd=os.getcwd(),
-                event_name=HookEvent.AFTER_LLM,
-                timestamp=str(time.time()),
-                agent_name=self.name,
-                messages=messages,
-                response=str(final_response),
-                model=self.llm if isinstance(self.llm, str) else str(self.llm),
-                latency_ms=(time.time() - start_time) * 1000
-            )
-            self._hook_runner.execute_sync(HookEvent.AFTER_LLM, after_llm_input)
+            if self._hook_runner.registry.has_hooks(HookEvent.AFTER_LLM):
+                after_llm_input = AfterLLMInput(
+                    session_id=getattr(self, '_session_id', 'default'),
+                    cwd=os.getcwd(),
+                    event_name=HookEvent.AFTER_LLM,
+                    timestamp=str(time.time()),
+                    agent_name=self.name,
+                    messages=messages,
+                    response=str(final_response),
+                    model=self.llm if isinstance(self.llm, str) else str(self.llm),
+                    latency_ms=(time.time() - start_time) * 1000
+                )
+                self._hook_runner.execute_sync(HookEvent.AFTER_LLM, after_llm_input)
            
            return final_response

@@ -1609,7 +1726,22 @@ Your Goal: {self.goal}"""
                if next_model:
                    current_model = self.llm if isinstance(self.llm, str) else str(self.llm)
                    logging.info(f"[{self.name}] {current_model} unavailable — falling back to {next_model}")
-                    
+
+                    # Surface the otherwise-silent switch as an observable event.
+                    # Forward the active stream callback so streaming consumers
+                    # receive the MODEL_FALLBACK event when this follows a
+                    # streaming request.
+                    _sync_stream_callback = (
+                        self.stream_emitter.emit if hasattr(self, 'stream_emitter') else None
+                    )
+                    self._emit_model_fallback(
+                        from_model=current_model,
+                        to_model=next_model,
+                        reason_category=classification.error_category,
+                        fallback_index=_fallback_index,
+                        stream_callback=_sync_stream_callback,
+                    )
+
                    # Apply backoff if suggested
                    if classification.backoff_seconds and classification.backoff_seconds > 0:
                        time.sleep(classification.backoff_seconds)
@@ -1772,7 +1904,20 @@ Your Goal: {self.goal}"""
            if next_model:
                current_model = self.llm if isinstance(self.llm, str) else str(self.llm)
                logging.info(f"[{self.name}] {current_model} unavailable — falling back to {next_model}")
-                
+
+                # Surface the otherwise-silent switch as an observable event.
+                # Await the async emitter so MODEL_FALLBACK hooks run in the
+                # active event loop, and honour emit_events so internal calls
+                # (emit_events=False) don't leak a stream event into the public
+                # stream.
+                await self._aemit_model_fallback(
+                    from_model=current_model,
+                    to_model=next_model,
+                    reason_category=classification.error_category,
+                    fallback_index=_fallback_index,
+                    stream_callback=stream_callback if emit_events else None,
+                )
+
                # Apply backoff if suggested
                if classification.backoff_seconds and classification.backoff_seconds > 0:
                    await asyncio.sleep(classification.backoff_seconds)
@@ -2312,7 +2457,7 @@ Your Goal: {self.goal}"""
            return output
        
        try:
-            run_id = getattr(self, '_run_id', None)
+            run_id = getattr(self, '_current_run_id', None)
            return self.context_manager.truncate_tool_output(tool_name, output, tool_call_id, run_id)
        except Exception as e:
            logging.warning(f"Tool output truncation error: {e}")
@@ -2447,8 +2592,7 @@ Your Goal: {self.goal}"""
        """Internal chat implementation (extracted for trace wrapping)."""
        # Reset the per-turn tool buffer so the self-improve review policy only
        # sees tools used in this turn (not during a nested skill-review turn).
-        if not getattr(self, "_in_skill_review", False):
-            self._turn_tools_used = []
+        self._reset_turn_tools()
        # Apply rate limiter if configured (before any LLM call)
        if self._rate_limiter is not None:
            self._rate_limiter.acquire()
@@ -3049,8 +3193,7 @@ Output MUST be JSON with 'reflection' and 'satisfactory'.
        """Internal async chat implementation (extracted for trace wrapping)."""
        # Reset the per-turn tool buffer so the self-improve review policy only
        # sees tools used in this turn (not during a nested skill-review turn).
-        if not getattr(self, "_in_skill_review", False):
-            self._turn_tools_used = []
+        self._reset_turn_tools()
        # C2 - cooperative cancellation: abort early if a pre-set token is given
        _cancel = cancel_token if cancel_token is not None else getattr(self, "interrupt_controller", None)
        if _cancel is not None and getattr(_cancel, "is_set", lambda: False)():
@@ -3718,62 +3861,31 @@ Output MUST be JSON with 'reflection' and 'satisfactory'.
                        logging.error(f"Failed to parse tool arguments as JSON: {json_error}")
                        arguments = {}
                    
-                    # Find the matching tool
-                    tool = next((t for t in tools if t.__name__ == function_name), None)
+                    # Find the matching tool by comparing every supported identifier:
+                    # __name__ (plain callables), .name (BaseTool instances like
+                    # BrowserBaseTool, or aliased FunctionTools), or the class name.
+                    # Compare all candidates (not short-circuit) so an aliased .name
+                    # that differs from __name__ still resolves and BaseTool
+                    # subclasses without __name__ do not crash dispatch.
+                    tool = next(
+                        (t for t in tools if function_name in (
+                            getattr(t, "__name__", None),
+                            getattr(t, "name", None),
+                            type(t).__name__,
+                        )),
+                        None,
+                    )
                    if not tool:
                        _get_display_functions()['display_error'](f"Tool {function_name} not found")
                        continue

-                    # --- BEFORE_TOOL hook ---
-                    try:
-                        from ..hooks import HookEvent, BeforeToolInput
-                        _before_tool_input = BeforeToolInput(
-                            session_id=getattr(self, '_session_id', 'default'),
-                            cwd=os.getcwd(),
-                            event_name=HookEvent.BEFORE_TOOL,
-                            timestamp=str(time.time()),
-                            agent_name=self.name,
-                            tool_name=function_name,
-                            tool_input=arguments,
-                        )
-                        _before_results = await self._hook_runner.execute(HookEvent.BEFORE_TOOL, _before_tool_input)
-                        _tool_blocked = self._hook_runner.is_blocked(_before_results)
-                    except Exception as _hook_err:
-                        logging.debug(f"BEFORE_TOOL hook error (non-fatal): {_hook_err}")
-                        _tool_blocked = False
-                    if _tool_blocked:
-                        # Reason extraction must not be able to re-open a block:
-                        # use attributes present on both HookResult (plugin
-                        # bridge) and HookOutput, defaulting safely.
-                        _block_reason = next(
-                            (getattr(r.output, "reason", None) for r in _before_results
-                             if r.output and getattr(r.output, "is_denied", lambda: False)()),
-                            None,
-                        ) or "Blocked by hook"
-                        results.append(f"[Tool blocked by hook: {_block_reason}]")
-                        continue
-
-                    # Route through safety pipeline instead of direct execution
+                    # Route through safety pipeline instead of direct execution.
+                    # BEFORE_TOOL/AFTER_TOOL hooks (blocking, arg mutation and
+                    # after-context aggregation) are fired once, guarded, inside
+                    # execute_tool_async — no inline duplicate dispatch here.
                    # Pass the tools list to honor task-scoped tools
                    result = await self.execute_tool_async(function_name, arguments, tools_override=tools)

-                    # --- AFTER_TOOL hook ---
-                    try:
-                        from ..hooks import AfterToolInput
-                        _after_tool_input = AfterToolInput(
-                            session_id=getattr(self, '_session_id', 'default'),
-                            cwd=os.getcwd(),
-                            event_name=HookEvent.AFTER_TOOL,
-                            timestamp=str(time.time()),
-                            agent_name=self.name,
-                            tool_name=function_name,
-                            tool_input=arguments,
-                            tool_output=result,
-                        )
-                        await self._hook_runner.execute(HookEvent.AFTER_TOOL, _after_tool_input)
-                    except Exception as _hook_err:
-                        logging.debug(f"AFTER_TOOL hook error (non-fatal): {_hook_err}")
-                    
                    results.append(result)
                except Exception as e:
                    _get_display_functions()['display_error'](f"Error executing tool {function_name}: {e}")
@@ -3862,8 +3974,9 @@ Output MUST be JSON with 'reflection' and 'satisfactory'.
        
        # Force streaming, no display by default (app-friendly)
        kwargs['stream'] = True
-        
-        # Use the internal streaming generator
+
+        # Use the internal streaming generator (guardrail-bypass warning is
+        # emitted inside _start_stream so it covers start(stream=True) too).
        for chunk in self._start_stream(prompt, **kwargs):
            yield chunk
        
@@ -3872,6 +3985,17 @@ Output MUST be JSON with 'reflection' and 'satisfactory'.

    def _start_stream(self, prompt: str, **kwargs) -> Generator[str, None, None]:
        """Stream generator for real-time response chunks."""
+        # Warn if an output guardrail is configured: token-level streaming
+        # yields chunks before a full response exists to validate, so the
+        # guardrail cannot be applied without breaking the streaming contract.
+        # This lives here (the single common streaming path) so both
+        # iter_stream() and start(stream=True) surface the bypass loudly.
+        if getattr(self, 'guardrail', None) is not None:
+            logging.warning(
+                f"Agent {getattr(self, 'name', '')}: output guardrail is not "
+                "applied to streamed responses (iter_stream / stream=True). "
+                "Use chat() for guardrail-validated output."
+            )
        try:
            # Reset the final display flag for each new conversation
            self._final_display_shown = False
@@ -12,7 +12,6 @@ Usage::
 """

 import json
-import logging
 from praisonaiagents._logging import get_logger
 import os
 import time
@@ -34,7 +34,6 @@ Example:
 """

 import os
-import logging
 from praisonaiagents._logging import get_logger
 import time
 import asyncio
@@ -28,6 +28,44 @@ _server_started: Dict[int, bool] = {}
 _registered_agents: Dict[int, Dict[str, str]] = {}
 _shared_apps: Dict[int, Any] = {}

+
+def cleanup_launch_registration(agent_id: str) -> None:
+    """Remove launch() endpoints registered for ``agent_id`` from the shared
+    HTTP state that ``Agent.launch()`` actually populates.
+
+    ``Agent.launch()`` writes routes into the module-level ``_registered_agents``
+    and ``_shared_apps`` dicts above. This tears those routes back down so a
+    closed agent's endpoint stops accepting requests and the request handler
+    closure no longer keeps the Agent object graph alive.
+    """
+    with _server_lock:
+        for port, paths in list(_registered_agents.items()):
+            stale_paths = [p for p, aid in paths.items() if aid == agent_id]
+            for p in stale_paths:
+                del paths[p]
+                app = _shared_apps.get(port)
+                if app is not None:
+                    try:
+                        # Only drop the agent-owned POST route. launch() always
+                        # registers the handler via ``.post(path)``, so filtering
+                        # on both path AND method preserves unrelated routes that
+                        # share the path with a different verb (e.g. the built-in
+                        # GET /health and GET /).
+                        app.router.routes = [
+                            r for r in app.router.routes
+                            if not (
+                                getattr(r, "path", None) == p
+                                and "POST" in (getattr(r, "methods", None) or set())
+                            )
+                        ]
+                        # Invalidate cached OpenAPI schema so removed routes
+                        # disappear from /openapi.json and /docs.
+                        app.openapi_schema = None
+                    except Exception:
+                        pass
+            if not paths:
+                _registered_agents.pop(port, None)
+
 if TYPE_CHECKING:
    pass

@@ -125,16 +163,30 @@ class ExecutionMixin:
        
        Args:
            prompt: The input prompt to process
-            **kwargs: Additional arguments passed to achat()
+            **kwargs: Additional arguments passed to achat():
+                - return_outcome (bool): If True, return a canonical
+                  ``RunOutcome`` (completed | hard_timeout | cancelled |
+                  aborted | failed) instead of raising on error/timeout/
+                  cancellation. Default: False.
+                - timeout (float): When used with ``return_outcome=True``,
+                  a hard timeout budget for the run.
            
        Returns:
-            The agent's response as a string, or AutonomyResult if autonomy enabled
+            The agent's response as a string, or AutonomyResult if autonomy
+            enabled, or a ``RunOutcome`` when ``return_outcome=True``.
            
        Note:
            If autonomy=True was set on the agent, astart() automatically uses
            the autonomous loop (run_autonomous_async) instead of single-turn chat.
        """
        import sys
+
+        return_outcome = kwargs.pop('return_outcome', False)
+        if return_outcome:
+            outcome_timeout = kwargs.pop('timeout', None)
+            return await self._astart_with_outcome(
+                prompt, outcome_timeout, **kwargs
+            )
        
        # ─────────────────────────────────────────────────────────────────────
        # UNIFIED AUTONOMY API: If autonomy is enabled, route to run_autonomous_async
@@ -196,6 +248,57 @@ class ExecutionMixin:
        kwargs['stream'] = stream_requested
        return await self.achat(prompt, **kwargs)

+    async def _astart_with_outcome(self, prompt, timeout=None, **kwargs):
+        """Run astart() and normalise its result/exception into a RunOutcome.
+
+        Optionally enforces a hard run-level timeout budget. The budget is the
+        *authoritative* source of ``hard_timeout``: when our own
+        ``asyncio.wait_for`` fires we return ``hard_timeout`` directly, so a
+        nested operation timeout (which surfaces as a generic
+        ``asyncio.TimeoutError`` from inside the run) is never misreported as a
+        run-budget timeout — it falls through to ``failed`` via
+        ``RunOutcome.from_exception``.
+
+        External ``asyncio.CancelledError`` (e.g. the enclosing task being
+        cancelled during host shutdown) is re-raised, not swallowed, so
+        cooperative cancellation semantics are honoured.
+        """
+        import asyncio
+        from .run_outcome import RunOutcome
+
+        enforce_budget = timeout is not None and timeout > 0
+
+        # Enforce the run budget with an explicit deadline on a task we own, so
+        # that only *our* budget expiry maps to hard_timeout. This deliberately
+        # avoids ``asyncio.wait_for`` catching a bare inner ``TimeoutError``:
+        # a nested operation timeout raised inside the run must fall through to
+        # ``failed`` rather than be misreported as a run-budget ``hard_timeout``.
+        try:
+            if enforce_budget:
+                task = asyncio.ensure_future(self.astart(prompt, **kwargs))
+                try:
+                    done, _ = await asyncio.wait({task}, timeout=timeout)
+                except asyncio.CancelledError:
+                    # Enclosing task cancelled (e.g. host shutdown): cancel the
+                    # child and propagate so cooperative cancellation is honoured.
+                    task.cancel()
+                    raise
+                if task not in done:
+                    # Our budget expired first: authoritative, sticky hard_timeout.
+                    task.cancel()
+                    return RunOutcome(reason="hard_timeout")
+                result = task.result()
+            else:
+                result = await self.astart(prompt, **kwargs)
+        except asyncio.CancelledError:
+            # External cancellation of the awaiting task: honour asyncio
+            # cancellation / host shutdown by propagating instead of converting
+            # it into a benign RunOutcome.
+            raise
+        except Exception as exc:  # noqa: BLE001 - normalised into outcome
+            return RunOutcome.from_exception(exc)
+        return RunOutcome.completed(output=str(result) if result is not None else None)
+
    def run(self, prompt: str, **kwargs: Any) -> Optional[str]:
        """Execute agent silently and return structured result.
        
@@ -208,9 +311,14 @@ class ExecutionMixin:
            **kwargs: Additional arguments:
                - stream (bool): Force streaming if True. Default: False
                - output (str): Output preset override (rarely needed)
+                - return_outcome (bool): If True, return a canonical
+                  ``RunOutcome`` describing how the run ended
+                  (completed | hard_timeout | cancelled | aborted | failed)
+                  instead of raising on error. Default: False.
                
        Returns:
-            The agent's response as a string
+            The agent's response as a string, or a ``RunOutcome`` when
+            ``return_outcome=True``.
            
        Example:
            ```python
@@ -227,8 +335,14 @@ class ExecutionMixin:
            - Background processing
            - API endpoints
        """
+        return_outcome = kwargs.pop('return_outcome', False)
+
        # Check if external managed backend is configured
        if hasattr(self, 'backend') and self.backend is not None:
+            if return_outcome:
+                return self._run_with_outcome(
+                    lambda: self._delegate_to_backend(prompt, **kwargs)
+                )
            return self._delegate_to_backend(prompt, **kwargs)
        
        # Production defaults: no streaming, no display
@@ -242,17 +356,34 @@ class ExecutionMixin:
        
        # Load history context
        self._load_history_context()
-        
-        # Check if planning mode is enabled
-        if self.planning:
-            result = self._start_with_planning(prompt, **kwargs)
-        else:
-            result = self.chat(prompt, **kwargs)
-        
-        # Auto-save session if enabled
-        self._auto_save_session()
-        
-        return result
+
+        def _execute():
+            if self.planning:
+                _result = self._start_with_planning(prompt, **kwargs)
+            else:
+                _result = self.chat(prompt, **kwargs)
+            # Auto-save session if enabled
+            self._auto_save_session()
+            return _result
+
+        if return_outcome:
+            return self._run_with_outcome(_execute)
+
+        return _execute()
+
+    def _run_with_outcome(self, executor):
+        """Run ``executor`` and normalise its result/exception into a RunOutcome.
+
+        Keeps the canonical terminal-outcome logic in one place so callers get
+        a single, closed description of how the run ended instead of inferring
+        it from exception identity.
+        """
+        from .run_outcome import RunOutcome
+        try:
+            result = executor()
+        except BaseException as exc:  # noqa: BLE001 - normalised into outcome
+            return RunOutcome.from_exception(exc)
+        return RunOutcome.completed(output=str(result) if result is not None else None)

    def _delegate_to_backend(self, prompt: str, **kwargs) -> Optional[str]:
        """Delegate execution to external managed backend (e.g., ManagedAgentIntegration).
@@ -1146,13 +1277,9 @@ Write the complete compiled report:"""
        # Record the tool name for this turn so the self-improve review policy
        # sees async tool usage too (issue #3037). Mirrors the sync path in
        # _execute_tool_with_context; skipped during a guarded review turn so
-        # the review's own calls are not tracked and cannot recurse.
-        if not getattr(self, "_in_skill_review", False):
-            turn_tools = getattr(self, "_turn_tools_used", None)
-            if turn_tools is None:
-                self._turn_tools_used = []
-                turn_tools = self._turn_tools_used
-            turn_tools.append(function_name)
+        # the review's own calls are not tracked and cannot recurse. Locked so
+        # concurrent turns on the same Agent don't corrupt the buffer (#3307).
+        self._record_turn_tool(function_name)

        # Enforce BEFORE_TOOL/AFTER_TOOL security hooks for every async caller,
        # mirroring the sync execute_tool path in tool_execution.py. Without
@@ -1369,11 +1496,22 @@ Write the complete compiled report:"""
                    return policy_result  # Error dict
                _, arguments = policy_result

-            # Try to find the function in the override tools list first, then agent's tools list
+            # Try to find the function in the override tools list first, then agent's tools list.
+            # Resolve by BaseTool/FunctionTool ``.name`` (instances like BrowserBaseTool or
+            # aliased decorated tools), plain callable ``__name__``, or class name so async
+            # dispatch matches the robust sync resolution in _execute_tool_impl.
            func = None
            tools_to_search = tools_override if tools_override is not None else self.tools
+            from ..tools.base import BaseTool
            for tool in tools_to_search:
-                if (callable(tool) and getattr(tool, '__name__', '') == function_name):
+                if isinstance(tool, BaseTool) and getattr(tool, 'name', None) == function_name:
+                    func = tool
+                    break
+                if hasattr(tool, 'name') and getattr(tool, 'name', None) == function_name:
+                    func = tool
+                    break
+                if (callable(tool) and getattr(tool, '__name__', '') == function_name) or \
+                   (inspect.isclass(tool) and tool.__name__ == function_name):
                    func = tool
                    break
            
@@ -1381,17 +1519,40 @@ Write the complete compiled report:"""
                logging.error(f"Function {function_name} not found in tools")
                return {"error": f"Function {function_name} not found in tools"}

+            # Activate the tool-progress channel so tools running under the async
+            # path can stream incremental output (emit_tool_progress) and the
+            # built-in todo tool can publish live updates (emit_todo_update),
+            # mirroring the sync execute_tool path. Zero overhead when no stream
+            # callbacks are registered — the sink stays None and the contextvar
+            # is set to None (a no-op for emitters).
+            _progress_sink = None
+            _stream_emitter = self._get_existing_stream_emitter() if hasattr(self, "_get_existing_stream_emitter") else None
+            if _stream_emitter is not None and _stream_emitter.has_callbacks:
+                def _progress_sink(_event, _emitter=_stream_emitter):  # noqa: ANN001 — StreamEvent forwarder
+                    _event.tool_call = {"name": function_name, "id": tool_call_id}
+                    _event.agent_id = self.name
+                    _emitter.emit(_event)
+
+            from ..streaming.events import tool_progress_channel
+
            try:
-                if inspect.iscoroutinefunction(func):
+                # BaseTool instances (plugin system, e.g. BrowserBaseTool) are not
+                # directly callable — dispatch to their .run() method like the sync path.
+                call_target = func.run if isinstance(func, BaseTool) else func
+                if inspect.iscoroutinefunction(call_target):
                    logging.debug(f"Executing async function: {function_name}")
-                    result = await func(**arguments)
+                    with tool_progress_channel(_progress_sink):
+                        result = await call_target(**arguments)
                else:
                    logging.debug(f"Executing sync function in executor: {function_name}")
                    loop = asyncio.get_running_loop()
                    from ..trace.context_events import copy_context_to_callable
-                    result = await loop.run_in_executor(
-                        None, copy_context_to_callable(lambda: func(**arguments))
-                    )
+                    # Set the channel BEFORE copy_context_to_callable so the sink
+                    # propagates into the executor thread via contextvars.
+                    with tool_progress_channel(_progress_sink):
+                        result = await loop.run_in_executor(
+                            None, copy_context_to_callable(lambda: call_target(**arguments))
+                        )
                
                # Ensure result is JSON serializable
                logging.debug(f"Raw result from tool: {result}")
@@ -1474,229 +1635,194 @@ Write the complete compiled report:"""
                
        should_start = False
        with _server_lock:
-            # Initialize port-specific collections if needed
+            # Initialize port-specific collections if needed (once per port)
            if port not in _registered_agents:
                _registered_agents[port] = {}

-                # Initialize shared FastAPI app if not already created for this port
-                if _shared_apps.get(port) is None:
-                    _shared_apps[port] = FastAPI(
-                        title=f"PraisonAI Agents API (Port {port})",
-                        description="API for interacting with PraisonAI Agents"
+            # Initialize shared FastAPI app if not already created for this port
+            if _shared_apps.get(port) is None:
+                _shared_apps[port] = FastAPI(
+                    title=f"PraisonAI Agents API (Port {port})",
+                    description="API for interacting with PraisonAI Agents"
+                )
+
+                # Add a root endpoint with a welcome message
+                @_shared_apps[port].get("/")
+                async def root():
+                    return {
+                        "message": f"Welcome to PraisonAI Agents API on port {port}. See /docs for usage.",
+                        "endpoints": list(_registered_agents[port].keys())
+                    }
+
+                # Add healthcheck endpoint
+                @_shared_apps[port].get("/health")
+                async def healthcheck():
+                    return {
+                        "status": "ok",
+                        "endpoints": list(_registered_agents[port].keys())
+                    }
+
+            # The path registration below must run on EVERY call, not just when the
+            # port is new, so multiple agents can share a single port.
+
+            # Normalize path to ensure it starts with /
+            if not path.startswith('/'):
+                path = f'/{path}'
+
+            # Check if path is already registered for this port
+            if path in _registered_agents[port]:
+                logging.warning(f"Path '{path}' is already registered on port {port}. Please use a different path.")
+                print(f"⚠️ Warning: Path '{path}' is already registered on port {port}.")
+                # Use a modified path to avoid conflicts
+                original_path = path
+                path = f"{path}_{self.agent_id[:6]}"
+                logging.warning(f"Using '{path}' instead of '{original_path}'")
+                print(f"🔄 Using '{path}' instead")
+
+            # Register the agent to this path
+            _registered_agents[port][path] = self.agent_id
+
+            # Define the endpoint handler
+            @_shared_apps[port].post(path)
+            async def handle_agent_query(request: Request, query_data: Optional[AgentQuery] = None):
+                # Handle both direct JSON with query field and form data
+                if query_data is None:
+                    try:
+                        request_data = await request.json()
+                        if "query" not in request_data:
+                            raise HTTPException(status_code=400, detail="Missing 'query' field in request")
+                        query = request_data["query"]
+                    except Exception:
+                        # Fallback to form data or query params
+                        form_data = await request.form()
+                        if "query" in form_data:
+                            query = form_data["query"]
+                        else:
+                            raise HTTPException(status_code=400, detail="Missing 'query' field in request")
+                else:
+                    query = query_data.query
+
+                try:
+                    # Use async version if available, otherwise use sync version
+                    if asyncio.iscoroutinefunction(self.chat):
+                        response = await self.achat(query, task_name=None, task_description=None, task_id=None)
+                    else:
+                        # Run sync function in a thread to avoid blocking
+                        loop = asyncio.get_running_loop()
+                        response = await loop.run_in_executor(None, lambda p=query: self.chat(p))
+
+                    return {"response": response}
+                except Exception as e:
+                    logging.error(f"Error processing query: {str(e)}", exc_info=True)
+                    return JSONResponse(
+                        status_code=500,
+                        content={"error": f"Error processing query: {str(e)}"}
                    )

-                    # Add a root endpoint with a welcome message
-                    @_shared_apps[port].get("/")
-                    async def root():
-                        return {
-                            "message": f"Welcome to PraisonAI Agents API on port {port}. See /docs for usage.",
-                            "endpoints": list(_registered_agents[port].keys())
-                        }
+            # Invalidate the cached OpenAPI schema so routes registered by later
+            # shared-port launch() calls still show up in /openapi.json and /docs.
+            # FastAPI caches app.openapi_schema on first access and does not
+            # regenerate it when new routes are added afterwards.
+            _shared_apps[port].openapi_schema = None

-                    # Add healthcheck endpoint
-                    @_shared_apps[port].get("/health")
-                    async def healthcheck():
-                        return {
-                            "status": "ok",
-                            "endpoints": list(_registered_agents[port].keys())
-                        }
+            print(f"🚀 Agent '{self.name}' available at http://{host}:{port}")

-                # Normalize path to ensure it starts with /
-                if not path.startswith('/'):
-                    path = f'/{path}'
-
-                # Check if path is already registered for this port
-                if path in _registered_agents[port]:
-                    logging.warning(f"Path '{path}' is already registered on port {port}. Please use a different path.")
-                    print(f"⚠️ Warning: Path '{path}' is already registered on port {port}.")
-                    # Use a modified path to avoid conflicts
-                    original_path = path
-                    path = f"{path}_{self.agent_id[:6]}"
-                    logging.warning(f"Using '{path}' instead of '{original_path}'")
-                    print(f"🔄 Using '{path}' instead")
-
-                # Register the agent to this path
-                _registered_agents[port][path] = self.agent_id
-
-                # Define the endpoint handler
-                @_shared_apps[port].post(path)
-                async def handle_agent_query(request: Request, query_data: Optional[AgentQuery] = None):
-                    # Handle both direct JSON with query field and form data
-                    if query_data is None:
-                        try:
-                            request_data = await request.json()
-                            if "query" not in request_data:
-                                raise HTTPException(status_code=400, detail="Missing 'query' field in request")
-                            query = request_data["query"]
-                        except Exception:
-                            # Fallback to form data or query params
-                            form_data = await request.form()
-                            if "query" in form_data:
-                                query = form_data["query"]
-                            else:
-                                raise HTTPException(status_code=400, detail="Missing 'query' field in request")
-                    else:
-                        query = query_data.query
-
-                    try:
-                        # Use async version if available, otherwise use sync version
-                        if asyncio.iscoroutinefunction(self.chat):
-                            response = await self.achat(query, task_name=None, task_description=None, task_id=None)
-                        else:
-                            # Run sync function in a thread to avoid blocking
-                            loop = asyncio.get_running_loop()
-                            response = await loop.run_in_executor(None, lambda p=query: self.chat(p))
-
-                        return {"response": response}
-                    except Exception as e:
-                        logging.error(f"Error processing query: {str(e)}", exc_info=True)
-                        return JSONResponse(
-                            status_code=500,
-                            content={"error": f"Error processing query: {str(e)}"}
-                        )
-
-                print(f"🚀 Agent '{self.name}' available at http://{host}:{port}")
-
-                # Check and mark server as started atomically to prevent race conditions
-                should_start = not _server_started.get(port, False)
-                if should_start:
-                    _server_started[port] = True
-
-            # Server start/wait outside the lock to avoid holding it during sleep  
+            # Check and mark server as started atomically to prevent race conditions
+            should_start = not _server_started.get(port, False)
            if should_start:
-                # Start the server in a separate thread
-                def run_server():
-                    try:
-                        print(f"✅ FastAPI server started at http://{host}:{port}")
-                        print(f"📚 API documentation available at http://{host}:{port}/docs")
-                        print(f"🔌 Available endpoints: {', '.join(list(_registered_agents[port].keys()))}")
-                        uvicorn.run(_shared_apps[port], host=host, port=port, log_level="debug" if debug else "info")
-                    except Exception as e:
-                        logging.error(f"Error starting server: {str(e)}", exc_info=True)
-                        print(f"❌ Error starting server: {str(e)}")
+                _server_started[port] = True

-                # Run server in a background thread
-                server_thread = threading.Thread(target=run_server, daemon=True)
-                server_thread.start()
-
-                # Wait for a moment to allow the server to start and register endpoints
-                self._safe_sleep(0.5)
-            else:
-                # If server is already running, wait a moment to make sure the endpoint is registered
-                self._safe_sleep(0.1)
-                print(f"🔌 Available endpoints on port {port}: {', '.join(list(_registered_agents[port].keys()))}")
-            
-            # Get the stack frame to check if this is the last launch() call in the script
-            import inspect
-            stack = inspect.stack()
-            
-            # If this is called from a Python script (not interactive), try to detect if it's the last launch call
-            if len(stack) > 1 and stack[1].filename.endswith('.py'):
-                caller_frame = stack[1]
-                caller_line = caller_frame.lineno
-                
+        # Server start/wait outside the lock to avoid holding it during sleep
+        if should_start:
+            # Start the server in a separate thread
+            def run_server():
                try:
-                    # Read the file to check if there are more launch calls after this one
-                    with open(caller_frame.filename, 'r') as f:
-                        lines = f.readlines()
-                    
-                    # Check if there are more launch() calls after the current line
-                    has_more_launches = False
-                    for line_content in lines[caller_line:]: # renamed line to line_content
-                        if '.launch(' in line_content and not line_content.strip().startswith('#'):
-                            has_more_launches = True
-                            break
-                    
-                    # If this is the last launch call, block the main thread
-                    if not has_more_launches:
-                        try:
-                            print("\nAll agents registered for HTTP mode. Press Ctrl+C to stop the servers.")
-                            while True:
-                                self._safe_sleep(1)
-                        except KeyboardInterrupt:
-                            print("\nServers stopped")
+                    print(f"✅ FastAPI server started at http://{host}:{port}")
+                    print(f"📚 API documentation available at http://{host}:{port}/docs")
+                    print(f"🔌 Available endpoints: {', '.join(list(_registered_agents[port].keys()))}")
+                    uvicorn.run(_shared_apps[port], host=host, port=port, log_level="debug" if debug else "info")
                except Exception as e:
-                    # If something goes wrong with detection, block anyway to be safe
-                    logging.error(f"Error in launch detection: {e}")
+                    logging.error(f"Error starting server: {str(e)}", exc_info=True)
+                    print(f"❌ Error starting server: {str(e)}")
+
+            # Run server in a background thread
+            server_thread = threading.Thread(target=run_server, daemon=True)
+            server_thread.start()
+
+            # Wait for a moment to allow the server to start and register endpoints
+            self._safe_sleep(0.5)
+        else:
+            # If server is already running, wait a moment to make sure the endpoint is registered
+            self._safe_sleep(0.1)
+            print(f"🔌 Available endpoints on port {port}: {', '.join(list(_registered_agents[port].keys()))}")
+
+        # Get the stack frame to check if this is the last launch() call in the script
+        import inspect
+        stack = inspect.stack()
+
+        # If this is called from a Python script (not interactive), try to detect if it's the last launch call
+        if len(stack) > 1 and stack[1].filename.endswith('.py'):
+            caller_frame = stack[1]
+            caller_line = caller_frame.lineno
+
+            try:
+                # Read the file to check if there are more launch calls after this one
+                with open(caller_frame.filename, 'r') as f:
+                    lines = f.readlines()
+
+                # Check if there are more launch() calls after the current line
+                has_more_launches = False
+                for line_content in lines[caller_line:]: # renamed line to line_content
+                    if '.launch(' in line_content and not line_content.strip().startswith('#'):
+                        has_more_launches = True
+                        break
+
+                # If this is the last launch call, block the main thread
+                if not has_more_launches:
                    try:
-                        print("\nKeeping HTTP servers alive. Press Ctrl+C to stop.")
+                        print("\nAll agents registered for HTTP mode. Press Ctrl+C to stop the servers.")
                        while True:
                            self._safe_sleep(1)
                    except KeyboardInterrupt:
                        print("\nServers stopped")
-            return None
+            except Exception as e:
+                # If something goes wrong with detection, block anyway to be safe
+                logging.error(f"Error in launch detection: {e}")
+                try:
+                    print("\nKeeping HTTP servers alive. Press Ctrl+C to stop.")
+                    while True:
+                        self._safe_sleep(1)
+                except KeyboardInterrupt:
+                    print("\nServers stopped")
+        return None

    def _launch_mcp_server(self, path: str, port: int, host: str, debug: bool):
        """
-        Launch MCP server (internal implementation).
-        
-        NOTE: This implementation will be moved to wrapper layer in future version.
-        For now, it maintains backward compatibility while following lazy import patterns.
+        Launch this single agent as an MCP server.
+
+        Delegates to the ``praisonai-mcp`` agent adapter via ``serve_agents([self])``
+        so that ``Agent.launch(protocol="mcp")`` and
+        ``PraisonAIAgents.launch(protocol="mcp")`` share one code path and one
+        vocabulary (publishing ``ask_{agent_name}`` + ``list_agents``). The mcp
+        package is an optional dependency imported lazily here so core keeps no
+        hard dependency on it.
        """
-        # For now, delegate to the existing MCP implementation 
-        # This will be extracted to a proper adapter in the future
        try:
-            import uvicorn
-            from mcp.server.fastmcp import FastMCP
-            from mcp.server.sse import SseServerTransport
-            from starlette.applications import Starlette
-            from starlette.routing import Mount
-            import threading
-            import time
-            import asyncio
-            
-            mcp_server_instance_name = f"{self.name}_mcp_server" if self.name else "agent_mcp_server"
-            mcp = FastMCP(mcp_server_instance_name)
+            from praisonai_mcp import serve_agents

-            # Determine the MCP tool name based on self.name
-            actual_mcp_tool_name = f"execute_{self.name.lower().replace(' ', '_').replace('-', '_')}_task" if self.name else "execute_task"
-
-            @mcp.tool(name=actual_mcp_tool_name)
-            async def execute_agent_task(prompt: str) -> str:
-                """Executes the agent's primary task with the given prompt."""
-                try:
-                    if hasattr(self, 'achat') and asyncio.iscoroutinefunction(self.achat):
-                        response = await self.achat(prompt, tools=self.tools, task_name=None, task_description=None, task_id=None)
-                    elif hasattr(self, 'chat'):
-                        from ..trace.context_events import copy_context_to_callable
-                        loop = asyncio.get_event_loop()
-                        response = await loop.run_in_executor(None, copy_context_to_callable(lambda p=prompt: self.chat(p, tools=self.tools)))
-                    else:
-                        return f"Error: Agent {self.name} misconfigured for MCP."
-                    return response if response is not None else "Agent returned no response."
-                except Exception as e:
-                    return f"Error executing task: {str(e)}"
-
-            # Create and run MCP server
-            base_path = (path or "/mcp").rstrip("/") or "/mcp"
-            transport = SseServerTransport(f"{base_path}/sse")
-            starlette_app = Starlette(
-                routes=[Mount(base_path, mcp.sse_app())]
+            # Keep the call inside the ImportError guard: serve_agents() lazily
+            # imports its transport backend, so a package that is installed
+            # without its optional transport extras surfaces the missing
+            # dependency here rather than at the import line above. Catching it
+            # in the same place yields one actionable install message instead of
+            # an uncaught traceback.
+            return serve_agents([self], host=host, port=port)
+        except ImportError:
+            _get_display_functions()['display_error'](
+                "MCP serving requires the 'praisonai-mcp' package."
            )
-
-            def run_mcp_server():
-                try:
-                    uvicorn.run(starlette_app, host=host, port=port, log_level="debug" if debug else "info")
-                except Exception as e:
-                    logging.error(f"Error starting MCP server: {str(e)}", exc_info=True)
-
-            server_thread = threading.Thread(target=run_mcp_server, daemon=True)
-            server_thread.start()
-            self._safe_sleep(0.5)
-
-            try:
-                print("\nKeeping MCP server alive. Press Ctrl+C to stop.")
-                while True:
-                    self._safe_sleep(1)
-            except KeyboardInterrupt:
-                print("\nMCP Server stopped")
+            print("\nTo add MCP capabilities, install: pip install praisonai-mcp")
            return None
-            
-        except ImportError as e:
-            missing_module = str(e).split("No module named '")[-1].rstrip("'")
-            _get_display_functions()['display_error'](f"Missing dependency: {missing_module}. Required for MCP mode.")
-            print(f"\nTo add MCP capabilities, install: pip install {missing_module}")
-            return None 

    async def _emit_retry_hook_async(self, tool_name, attempt, delay_ms, error, max_attempts, error_type):
        """Emit ON_RETRY hook event (async version).
@@ -14,9 +14,9 @@ from typing import Optional, Any, Callable, Dict, List, Union, TYPE_CHECKING, Li
 from dataclasses import dataclass, field
 from enum import Enum
 import inspect
-import logging
 from praisonaiagents._logging import get_logger
 import asyncio
+import contextvars
 import threading
 import time
 import json
@@ -163,33 +163,52 @@ from ..errors import (
    HandoffValidationError
 )

-# Thread-local storage for tracking handoff chains
-_handoff_context = threading.local()
+# Per-task/per-thread storage for tracking handoff chains.
+#
+# ``contextvars.ContextVar`` isolates the chain per :class:`asyncio.Task`
+# (and per OS thread), unlike ``threading.local()`` which shares one list
+# across every coroutine running on the same event-loop thread. Concurrent
+# async handoffs (``asyncio.gather``, a server handling parallel requests, or
+# any ``max_concurrent`` workflow) would otherwise push/pop into the same list
+# and corrupt each other's cycle/depth state. Combined with the copy-on-write
+# push/pop below, this fully isolates sibling handoff tasks (e.g. those spawned
+# by ``parallel_handoffs`` via ``asyncio.gather``).
+_handoff_chain_var: "contextvars.ContextVar[Optional[List[str]]]" = contextvars.ContextVar(
+    "handoff_chain", default=None
+)

 def _get_handoff_chain() -> List[str]:
-    """Get current handoff chain from thread-local storage."""
-    if not hasattr(_handoff_context, 'chain'):
-        _handoff_context.chain = []
-    return _handoff_context.chain
+    """Get current handoff chain for this task/thread."""
+    chain = _handoff_chain_var.get()
+    if chain is None:
+        chain = []
+        _handoff_chain_var.set(chain)
+    return chain

 def _get_handoff_depth() -> int:
    """Get current handoff depth."""
    return len(_get_handoff_chain())

 def _push_handoff(agent_name: str) -> None:
-    """Push agent to handoff chain."""
-    chain = _get_handoff_chain()
+    """Push agent to handoff chain.
+
+    Uses copy-on-write so a push made inside a child task does not leak back
+    into the parent task's chain once the child completes.
+    """
+    chain = list(_get_handoff_chain())
    chain.append(agent_name)
+    _handoff_chain_var.set(chain)

 def _pop_handoff() -> Optional[str]:
    """Pop agent from handoff chain."""
-    chain = _get_handoff_chain()
-    return chain.pop() if chain else None
+    chain = list(_get_handoff_chain())
+    popped = chain.pop() if chain else None
+    _handoff_chain_var.set(chain)
+    return popped

 def _clear_handoff_chain() -> None:
    """Clear the handoff chain."""
-    if hasattr(_handoff_context, 'chain'):
-        _handoff_context.chain = []
+    _handoff_chain_var.set([])

@dataclass
 class HandoffInputData:
@@ -289,12 +308,14 @@ class Handoff:
    - Cycle detection and depth limiting
    - Configurable context policies
    """
-    
-    # Class-level semaphore for concurrency control
-    _semaphore: Optional[asyncio.Semaphore] = None
-    _sync_semaphore: Optional[threading.Semaphore] = None
-    _semaphore_lock: threading.Lock = threading.Lock()  # Lock for semaphore initialization
-    
+
+    # Class-level lock guarding lazy creation of each instance's async
+    # semaphore. The semaphore itself is per-instance (so every Handoff
+    # enforces its own max_concurrent), but the brief init critical section is
+    # only ever touched under this shared threading.Lock, which keeps
+    # double-checked lazy creation thread-safe without a per-instance lock.
+    _semaphore_lock: threading.Lock = threading.Lock()
+
    def __init__(
        self,
        agent: 'Agent',
@@ -325,10 +346,40 @@ class Handoff:
        self.input_type = input_type
        self.input_filter = input_filter
        self.config = config or HandoffConfig()
+
+        # Instance-level concurrency control. Each Handoff enforces its own
+        # max_concurrent instead of sharing one process-wide semaphore, so
+        # different handoffs don't silently override each other's limits based
+        # on execution order. The async semaphore is created lazily (and
+        # recreated if bound to a stale event loop) since it binds to the
+        # running loop on first use.
+        self._semaphore: Optional[asyncio.Semaphore] = None
+        self._semaphore_loop: Optional[asyncio.AbstractEventLoop] = None
        
        # Override config callback if on_handoff provided directly
        if on_handoff and not self.config.on_handoff:
            self.config.on_handoff = on_handoff
+
+    def _get_semaphore(self) -> Optional[asyncio.Semaphore]:
+        """Return this handoff's async semaphore, bound to the current loop.
+
+        Returns None when concurrency limiting is disabled (max_concurrent <= 0).
+        The semaphore is created lazily and recreated if the running event loop
+        differs from the one it was originally bound to, so a process that calls
+        asyncio.run(...) more than once doesn't crash with a "bound to a
+        different event loop" RuntimeError.
+        """
+        if self.config.max_concurrent <= 0:
+            return None
+        try:
+            current_loop = asyncio.get_event_loop()
+        except RuntimeError:
+            current_loop = None
+        with self._semaphore_lock:
+            if self._semaphore is None or self._semaphore_loop is not current_loop:
+                self._semaphore = asyncio.Semaphore(self.config.max_concurrent)
+                self._semaphore_loop = current_loop
+            return self._semaphore
        
    @property
    def tool_name(self) -> str:
@@ -597,13 +648,15 @@ class Handoff:
        """
        start_time = time.time()
        kwargs = context or {}
+        pushed = False
        
        try:
-            # Safety checks
+            # Safety checks (may raise before anything is pushed for this call)
            self._check_safety(source_agent)
            
            # Track handoff chain
            _push_handoff(source_agent.name)
+            pushed = True
            
            # Execute on_handoff callback
            self._execute_callback(self.config.on_handoff or self.on_handoff, source_agent, kwargs)
@@ -679,7 +732,8 @@ class Handoff:
            logger.error(f"Handoff error: {e}")
            return result
        finally:
-            _pop_handoff()
+            if pushed:
+                _pop_handoff()
    
    async def execute_async(
        self,
@@ -698,20 +752,19 @@ class Handoff:
        Returns:
            HandoffResult with response or error
        """
-        # Initialize semaphore if needed (thread-safe)
-        if self.config.max_concurrent > 0 and Handoff._semaphore is None:
-            with Handoff._semaphore_lock:  # Thread-safe initialization
-                if Handoff._semaphore is None:  # Double-check after acquiring lock
-                    Handoff._semaphore = asyncio.Semaphore(self.config.max_concurrent)
+        # Per-instance semaphore, bound to the current event loop
+        semaphore = self._get_semaphore()
        
        start_time = time.time()
        kwargs = context or {}
        
        async def _execute():
+            pushed = False
            try:
-                # Safety checks
+                # Safety checks (may raise before anything is pushed for this call)
                self._check_safety(source_agent)
                _push_handoff(source_agent.name)
+                pushed = True
                
                # Execute callback
                self._execute_callback(self.config.on_handoff or self.on_handoff, source_agent, kwargs)
@@ -760,11 +813,12 @@ class Handoff:
                
                return result
            finally:
-                _pop_handoff()
+                if pushed:
+                    _pop_handoff()
        
        try:
-            if self.config.max_concurrent > 0 and Handoff._semaphore:
-                async with Handoff._semaphore:
+            if semaphore is not None:
+                async with semaphore:
                    if self.config.timeout_seconds > 0:
                        result = await asyncio.wait_for(
                            _execute(),
@@ -828,13 +882,15 @@ class Handoff:
        def handoff_tool(**kwargs):
            """Execute the handoff to the target agent."""
            start_time = time.time()
+            pushed = False
            
            try:
-                # Safety checks
+                # Safety checks (may raise before anything is pushed for this call)
                self._check_safety(source_agent)
                
                # Track handoff chain
                _push_handoff(source_agent.name)
+                pushed = True
                
                # Execute on_handoff callback
                self._execute_callback(self.config.on_handoff or self.on_handoff, source_agent, kwargs)
@@ -920,7 +976,8 @@ class Handoff:
                self._execute_callback(self.config.on_error, source_agent, kwargs, result)
                return f"Error during handoff to {self.agent.name}: {str(e)}"
            finally:
-                _pop_handoff()
+                if pushed:
+                    _pop_handoff()
        
        # Set function metadata for tool definition generation
        handoff_tool.__name__ = self.tool_name
@@ -1171,6 +1228,13 @@ async def parallel_handoffs(
    semaphore = asyncio.Semaphore(effective_max_concurrent) if effective_max_concurrent > 0 else None
    
    async def _run_one(agent, prompt):
+        # Each gathered task shares a copied context, but a copied ContextVar
+        # binding still points at the *same* parent list object. Rebind to a
+        # fresh, per-task copy so sibling handoffs cannot corrupt each other's
+        # cycle/depth tracking when parallel_handoffs runs inside a non-empty
+        # parent handoff chain.
+        _handoff_chain_var.set(list(_handoff_chain_var.get() or []))
+
        async def _do_handoff():
            try:
                return await source.handoff_to_async(agent, prompt, config=config)
@@ -1391,13 +1455,15 @@ class TypedHandoff(Handoff, Generic[T]):
        
        start_time = time.time()
        kwargs = context or {}
+        pushed = False
        
        try:
-            # Safety checks
+            # Safety checks (may raise before anything is pushed for this call)
            self._check_safety(source_agent)
            
            # Track handoff chain
            _push_handoff(source_agent.name)
+            pushed = True
            
            # Execute on_handoff callback
            self._execute_callback(self.config.on_handoff or self.on_handoff, source_agent, kwargs)
@@ -1470,7 +1536,8 @@ class TypedHandoff(Handoff, Generic[T]):
            logger.error(f"Typed handoff error: {e}")
            return result
        finally:
-            _pop_handoff()
+            if pushed:
+                _pop_handoff()
    
    async def execute_async(
        self,
@@ -1497,20 +1564,19 @@ class TypedHandoff(Handoff, Generic[T]):
        if isinstance(payload, str):
            return await super().execute_async(source_agent, payload, context)
        
-        # Initialize semaphore if needed (thread-safe)
-        if self.config.max_concurrent > 0 and Handoff._semaphore is None:
-            with Handoff._semaphore_lock:
-                if Handoff._semaphore is None:
-                    Handoff._semaphore = asyncio.Semaphore(self.config.max_concurrent)
+        # Per-instance semaphore, bound to the current event loop
+        semaphore = self._get_semaphore()
        
        start_time = time.time()
        kwargs = context or {}
        
        async def _execute():
+            pushed = False
            try:
-                # Safety checks
+                # Safety checks (may raise before anything is pushed for this call)
                self._check_safety(source_agent)
                _push_handoff(source_agent.name)
+                pushed = True
                
                # Execute callback
                self._execute_callback(self.config.on_handoff or self.on_handoff, source_agent, kwargs)
@@ -1558,11 +1624,12 @@ class TypedHandoff(Handoff, Generic[T]):
                    handoff_depth=_get_handoff_depth(),
                )
            finally:
-                _pop_handoff()
+                if pushed:
+                    _pop_handoff()
        
        try:
-            if self.config.max_concurrent > 0 and Handoff._semaphore:
-                async with Handoff._semaphore:
+            if semaphore is not None:
+                async with semaphore:
                    if self.config.timeout_seconds > 0:
                        result = await asyncio.wait_for(
                            _execute(),
@@ -13,7 +13,6 @@ Usage::
 """

 import asyncio
-import logging
 from praisonaiagents._logging import get_logger
 import threading
 import time
@@ -22,7 +22,6 @@ from __future__ import annotations

 import hashlib
 import json
-import logging
 from praisonaiagents._logging import get_logger
 import time
 from dataclasses import dataclass, field
@@ -240,21 +240,25 @@ class MemoryMixin:
            if hasattr(self._history_lock, 'is_async_context') and self._history_lock.is_async_context():
                # Cannot use asyncio.Lock in sync context - use thread lock as fallback
                import hashlib
+                import uuid
                from datetime import datetime, timezone
                with self._history_lock._lock._thread_lock:
                    if self._session_id is None:  # Double-check after acquiring lock
                        hour_str = datetime.now(timezone.utc).strftime("%Y%m%d%H")
                        agent_hash = hashlib.sha256((self.name or "agent").encode()).hexdigest()[:6]
-                        self._session_id = f"{hour_str}-{agent_hash}"
+                        # per-instance suffix so same-named agents can never collide
+                        self._session_id = f"{hour_str}-{agent_hash}-{uuid.uuid4().hex[:8]}"
            else:
                # Use sync lock directly
                import hashlib
+                import uuid
                from datetime import datetime, timezone
                with self._history_lock.lock():
                    if self._session_id is None:  # Double-check after acquiring lock
                        hour_str = datetime.now(timezone.utc).strftime("%Y%m%d%H")
                        agent_hash = hashlib.sha256((self.name or "agent").encode()).hexdigest()[:6]
-                        self._session_id = f"{hour_str}-{agent_hash}"
+                        # per-instance suffix so same-named agents can never collide
+                        self._session_id = f"{hour_str}-{agent_hash}-{uuid.uuid4().hex[:8]}"
        
        # Call db adapter's on_agent_start to get previous messages
        try:
@@ -8,7 +8,6 @@ Thread-safe implementation for concurrent access.
 import threading
 import heapq
 import time
-import logging
 from praisonaiagents._logging import get_logger
 from typing import Optional, Any, List, Tuple
 from dataclasses import dataclass, field
@@ -0,0 +1,138 @@
+"""Prompt-cache-stability contract for the Agent turn (Issue #3352).
+
+Provider prompt caching (Anthropic/OpenAI) only hits when the *leading* bytes
+of a request are byte-identical to the previous request. For a long-lived
+conversation the cached prefix — the system instructions, the serialised tool
+schemas, and the model identity — is the dominant cost and latency lever.
+
+Gateways run many users on a single shared ``Agent`` instance and swap
+``tools``/``llm`` in and out per turn (per-route tool scoping, per-user
+``/model`` override). Those swaps silently change the cached prefix and the
+provider cache misses with zero operator visibility.
+
+``prompt_prefix_signature`` gives callers a single, cheap, deterministic
+fingerprint of exactly the cache-relevant inputs — model, the sorted set of
+tool names, and a fingerprint of the system instructions — and *nothing*
+volatile per-turn (arrival time, routing facts, memory/RAG recall). When the
+signature is unchanged across turns the prefix is guaranteed stable, so the
+provider cache keeps hitting; when it changes, that is the one auditable point
+at which cache warmth is knowingly sacrificed.
+"""
+
+from __future__ import annotations
+
+import hashlib
+from typing import Any
+
+
+def _tool_name(tool: Any) -> str:
+    """Best-effort stable name for a tool entry.
+
+    Tools may be plain callables, dicts holding an OpenAI-style function
+    schema, or objects exposing ``__name__``/``name``. The name identifies the
+    schema slot in the serialised tool block.
+    """
+    if isinstance(tool, dict):
+        fn = tool.get("function")
+        if isinstance(fn, dict) and fn.get("name"):
+            return str(fn["name"])
+        for key in ("name", "type"):
+            if tool.get(key):
+                return str(tool[key])
+        return str(sorted(tool.keys()))
+    for attr in ("__name__", "name"):
+        value = getattr(tool, attr, None)
+        if value:
+            return str(value)
+    return str(tool)
+
+
+def _tool_fingerprint(tool: Any) -> str:
+    """Best-effort stable fingerprint of a tool's *provider-visible* schema.
+
+    The serialised tool block sent to the provider is not just the tool name —
+    it is the full function schema (name + description + parameters). A change
+    to a tool's description, parameters, or required fields *without* a rename
+    changes those bytes and therefore invalidates the prompt cache, so the
+    fingerprint must reflect the whole schema, not only the name (Issue #3352
+    review). Falls back to the name when no richer schema is exposed.
+    """
+    name = _tool_name(tool)
+
+    # Dict tools already carry an OpenAI-style function schema — fingerprint the
+    # description + parameters alongside the name so a same-name schema edit is
+    # detected. ``json.dumps(sort_keys=True)`` makes the render deterministic.
+    if isinstance(tool, dict):
+        fn = tool.get("function")
+        schema = fn if isinstance(fn, dict) else tool
+        desc = schema.get("description") if isinstance(schema, dict) else None
+        params = schema.get("parameters") if isinstance(schema, dict) else None
+        try:
+            import json
+
+            return "\x01".join(
+                (
+                    name,
+                    str(desc or ""),
+                    json.dumps(params or {}, sort_keys=True, default=str),
+                )
+            )
+        except Exception:  # pragma: no cover — defensive
+            return name
+
+    # Callable/object tools: fold in the docstring (the description the schema
+    # generator emits) so an edited tool doc flips the signature too.
+    doc = getattr(tool, "__doc__", None)
+    if doc:
+        return f"{name}\x01{doc}"
+    return name
+
+
+def prompt_prefix_signature(agent: Any) -> str:
+    """Return a sha256 signature of an agent's cache-relevant prompt prefix.
+
+    The signature is computed over, and only over:
+
+    * the model identity (``agent.llm``),
+    * the sorted set of tool *schema fingerprints* (name + description +
+      parameters, ``agent.tools``) — so a same-name schema edit is detected,
+    * a fingerprint of the system instructions (``agent.instructions``).
+
+    Volatile per-turn data is intentionally excluded so that an unchanged
+    route/model keeps a byte-identical prefix and the provider cache keeps
+    hitting. Callers compare the signature turn-over-turn: an unchanged value
+    means the cached prefix is reused; a changed value is the single auditable
+    point of prompt-cache invalidation.
+
+    Best-effort and never raises: any attribute access failure degrades the
+    corresponding component to an empty string rather than breaking the turn.
+    """
+    try:
+        llm = getattr(agent, "llm", None)
+        model = llm if isinstance(llm, str) else getattr(llm, "model", None) or str(llm)
+    except Exception:
+        model = ""
+
+    try:
+        tools = getattr(agent, "tools", None) or []
+        tool_fps = sorted(_tool_fingerprint(t) for t in tools)
+    except Exception:
+        tool_fps = []
+
+    try:
+        instructions = getattr(agent, "instructions", None) or ""
+        instructions = str(instructions)
+    except Exception:
+        instructions = ""
+
+    hasher = hashlib.sha256()
+    hasher.update(b"model\x00")
+    hasher.update(str(model).encode("utf-8", "replace"))
+    hasher.update(b"\x00tools\x00")
+    hasher.update("\x00".join(tool_fps).encode("utf-8", "replace"))
+    hasher.update(b"\x00instructions\x00")
+    hasher.update(instructions.encode("utf-8", "replace"))
+    return hasher.hexdigest()
+
+
+__all__ = ["prompt_prefix_signature"]
@@ -6,7 +6,6 @@ model selection based on task characteristics.
 """

 import os
-import logging
 from praisonaiagents._logging import get_logger
 from typing import Dict, List, Optional, Any, Union
 from .agent import Agent
@@ -0,0 +1,95 @@
+"""Canonical terminal-outcome contract for agent runs.
+
+A single, closed description of *how* a run ended, produced once by the core
+run and consumed everywhere. Long-running hosts (e.g. gateways/bots) can make
+delivery/retry/DLQ/status decisions from one field instead of inferring the
+terminal state from exception identity.
+
+Precedence is explicit and sticky: a ``hard_timeout`` is never silently
+downgraded by later cleanup. See ``RunOutcome.from_exception``.
+"""
+
+from dataclasses import dataclass
+from typing import Optional
+try:
+    from typing import Literal
+except ImportError:  # pragma: no cover - py<3.8 fallback
+    Literal = None  # type: ignore
+
+if Literal is not None:
+    TerminalReason = Literal[
+        "completed", "hard_timeout", "cancelled", "aborted", "failed"
+    ]
+else:  # pragma: no cover
+    TerminalReason = str  # type: ignore
+
+# Precedence: higher wins and is sticky (a hard timeout is not downgraded).
+_REASON_PRECEDENCE = {
+    "completed": 0,
+    "failed": 1,
+    "aborted": 2,
+    "cancelled": 3,
+    "hard_timeout": 4,
+}
+
+
+@dataclass(frozen=True)
+class RunOutcome:
+    """Closed, canonical description of how an agent run ended.
+
+    Attributes:
+        reason: One of ``completed | hard_timeout | cancelled | aborted | failed``.
+        output: Partial or final text, if any.
+        error: Redacted message when ``reason == "failed"``.
+    """
+
+    reason: "TerminalReason"
+    output: Optional[str] = None
+    error: Optional[str] = None
+
+    @property
+    def succeeded(self) -> bool:
+        """True only when the run completed normally."""
+        return self.reason == "completed"
+
+    @classmethod
+    def completed(cls, output: Optional[str] = None) -> "RunOutcome":
+        return cls(reason="completed", output=output)
+
+    @classmethod
+    def from_exception(
+        cls, exc: BaseException, output: Optional[str] = None
+    ) -> "RunOutcome":
+        """Normalise a raised exception into a canonical terminal outcome.
+
+        Maps well-known exception types to their terminal reason. Anything
+        unrecognised is treated as ``failed`` with a redacted message.
+
+        Note on ``hard_timeout``: the run-level budget is the authoritative
+        source of ``hard_timeout`` and is applied explicitly by the caller
+        (see ``_astart_with_outcome``). A bare ``asyncio.TimeoutError`` reaching
+        this normaliser is a *nested* operation timeout (e.g. a handoff/tool that
+        exhausted its own budget while the run budget remained) and is therefore
+        classified as ``failed`` — not silently promoted to a run-budget
+        ``hard_timeout``, which would drive the wrong host retry/DLQ decision.
+        Real cooperative cancellation is intercepted and re-raised by the run
+        wrapper (see ``_astart_with_outcome``) *before* it reaches this
+        normaliser, so host shutdown is honoured. A supersede/interrupt named
+        error that does surface here is a domain "cancelled" outcome.
+        """
+        import asyncio
+
+        if _name_matches(exc, ("hardtimeout", "runtimeout", "budgettimeout")):
+            return cls(reason="hard_timeout", output=output)
+        if isinstance(exc, asyncio.CancelledError) or _name_matches(
+            exc, ("supersed", "interrupt", "cancelled")
+        ):
+            return cls(reason="cancelled", output=output)
+        if _name_matches(exc, ("abort", "drain", "shutdown")):
+            return cls(reason="aborted", output=output)
+        return cls(reason="failed", output=output, error=str(exc))
+
+
+def _name_matches(exc: BaseException, needles: tuple) -> bool:
+    name = type(exc).__name__.lower()
+    return any(n in name for n in needles)
@@ -5,7 +5,6 @@ Provides automatic summarization when context window fills up.
 Reuses existing telemetry/token_collector for token tracking.
 """

-import logging
 from praisonaiagents._logging import get_logger
 from typing import Optional, List, Dict, Any

@@ -471,6 +471,46 @@ class ToolExecutionMixin:
            self._middleware_manager = manager
        return manager if manager.has_tool_hooks else None

+    def _get_turn_tools_lock(self):
+        """Return the DualLock guarding the per-turn tool buffer.
+
+        Falls back to a lazily-created lock so subclasses or objects that
+        predate the lock attribute stay safe. The lock protects
+        ``_turn_tools_used`` from corruption when concurrent chat()/achat()
+        turns run on the same Agent instance (issue #3307).
+        """
+        lock = getattr(self, "_turn_tools_lock", None)
+        if lock is None:
+            from .async_safety import DualLock
+            lock = DualLock()
+            self._turn_tools_lock = lock
+        return lock
+
+    def _reset_turn_tools(self):
+        """Reset the per-turn tool buffer under lock (start of a chat turn)."""
+        if getattr(self, "_in_skill_review", False):
+            return
+        with self._get_turn_tools_lock().sync():
+            self._turn_tools_used = []
+
+    def _record_turn_tool(self, function_name):
+        """Append a tool name to the per-turn buffer under lock."""
+        if getattr(self, "_in_skill_review", False):
+            return
+        with self._get_turn_tools_lock().sync():
+            turn_tools = getattr(self, "_turn_tools_used", None)
+            if turn_tools is None:
+                turn_tools = []
+                self._turn_tools_used = turn_tools
+            turn_tools.append(function_name)
+
+    def _drain_turn_tools(self):
+        """Return a copy of the per-turn buffer and clear it, under lock."""
+        with self._get_turn_tools_lock().sync():
+            tools_used = list(getattr(self, "_turn_tools_used", []) or [])
+            self._turn_tools_used = []
+        return tools_used
+
    def _execute_tool_with_context(self, function_name, arguments, state, tool_call_id=None):
        """Execute tool within injection context, with optional output truncation.
        
@@ -487,13 +527,9 @@ class ToolExecutionMixin:
        
        # Record the tool name for this turn so the self-improve review policy
        # can see what ran (issue #3037). Skipped during a guarded review turn
-        # to avoid tracking the review's own tool calls or recursing.
-        if not getattr(self, "_in_skill_review", False):
-            turn_tools = getattr(self, "_turn_tools_used", None)
-            if turn_tools is None:
-                self._turn_tools_used = []
-                turn_tools = self._turn_tools_used
-            turn_tools.append(function_name)
+        # to avoid tracking the review's own tool calls or recursing. Locked so
+        # concurrent turns on the same Agent don't corrupt the buffer (#3307).
+        self._record_turn_tool(function_name)

        # Emit tool call start event (zero overhead when not set)
        _trace_emitter = get_context_emitter()
@@ -836,12 +872,34 @@ class ToolExecutionMixin:
            # model-visible image parts via format_tool_result_messages().
            _is_multimodal_result = _normalize_multimodal_result(result) is not None

+            # Context economy: if the tool declared a compact, model-facing view
+            # (ToolResult.model_output, or a to_model_output(result) hook on the
+            # @tool/BaseTool), resolve it now while the FULL result is still
+            # intact for tracing/hooks/display below. The compact view is only
+            # swapped in at the very end, right before the string returned to
+            # the model is built, so downstream consumers keep the full payload.
+            _model_facing_override = None
+            if not _is_multimodal_result:
+                _model_facing_override = self._resolve_model_facing_result(
+                    function_name, result
+                )
+
            # Apply prompt injection protection for external tools
            # Zero-cost for trusted tools, wraps external content in security markers
            if not _is_multimodal_result:
                try:
                    from ..tools.trust import wrap_if_external
                    result = wrap_if_external(function_name, result)
+                    # The compact, model-facing view is untrusted external
+                    # content too when the producing tool is external, so it
+                    # MUST pass through the same prompt-injection fence before
+                    # it can reach the model. Resolving it above (pre-fence)
+                    # kept the full payload intact for hooks/tracing; fence the
+                    # override here so it never bypasses the security markers.
+                    if _model_facing_override is not None:
+                        _model_facing_override = wrap_if_external(
+                            function_name, _model_facing_override
+                        )
                except Exception:
                    # Trust module unavailable (partial/broken install) must not
                    # abort tool execution; fall through with the raw result.
@@ -934,8 +992,12 @@ class ToolExecutionMixin:
                    logging.debug(f"Tool truncation skipped: {e}")
            
            # Emit tool call end event (truncation handled by context_events.py)
+            # Only stringify the result if the emitter is actually enabled; the
+            # default emitter is a disabled NoOp, so str(result) would otherwise
+            # re-serialise the whole structure for nothing on every tool call.
            _duration_ms = (_time.time() - _tool_start_time) * 1000
-            _trace_emitter.tool_call_end(self.name, function_name, str(result) if result else None, _duration_ms)
+            if _trace_emitter.enabled:
+                _trace_emitter.tool_call_end(self.name, function_name, str(result) if result else None, _duration_ms)
            
            # Emit TOOL_CALL_RESULT to stream_emitter (for AIUI/AG-UI consumers)
            # Zero overhead when no callbacks registered
@@ -977,7 +1039,18 @@ class ToolExecutionMixin:
                    tool_error = self._last_normalized_result.error_message
                # Clean up temporary attribute
                delattr(self, '_last_normalized_result')
-            
+
+            # Context economy: ``result`` stays the FULL output through the
+            # AFTER_TOOL hook, result-aware loop detection, and the loop guard
+            # (below), so those channels keep seeing real, changing outcomes.
+            # A tool-declared compact model-facing view (if any) is only swapped
+            # in at the very end, right before ``return``, purely to shrink what
+            # the LLM sees. No override => behaviour is unchanged. Model-facing
+            # annotations added below (AFTER_TOOL additional_context, loop-guard
+            # notices) are collected here so they can be re-applied to the
+            # compact view and therefore always reach the model.
+            _model_facing_annotations = []
+
            # Only build the input if an AFTER_TOOL hook is actually registered
            if self._hook_runner.registry.has_hooks(HookEvent.AFTER_TOOL):
                after_tool_input = AfterToolInput(
@@ -1006,6 +1079,9 @@ class ToolExecutionMixin:
                        result.setdefault("_additional_context", extra_context)
                    else:
                        result = {"value": result, "_additional_context": extra_context}
+                    # Mirror any model-facing annotation onto the compact view so
+                    # it survives the context-economy swap at the end.
+                    _model_facing_annotations.append(extra_context)
            
            # Back-fill the result hash so the result-aware detector can tell a
            # genuine stall (identical output) from legitimate polling (changing
@@ -1049,10 +1125,28 @@ class ToolExecutionMixin:
                    else:
                        # Wrap non-string/dict/list results to preserve original data plus warning
                        result = {"value": result, "_loop_guard": {"message": decision.message, "action": decision.action.value}}
+                    # Ensure the loop-guard notice also reaches the model when a
+                    # compact model-facing view replaces ``result`` below.
+                    _model_facing_annotations.append(f"[loop-guard] {decision.message}")
            
            # Increment per-turn tool count for no-tool-call detection
            self._autonomy_turn_tool_count = getattr(self, '_autonomy_turn_tool_count', 0) + 1
-            
+
+            # Context economy: now that tracing, hooks, loop detection and the
+            # loop guard have all observed the FULL result, swap in the compact,
+            # tool-declared model-facing view for the LLM. Re-apply any
+            # model-facing annotations so they are never lost. No override =>
+            # the full result is returned exactly as before.
+            if _model_facing_override is not None:
+                result = _model_facing_override
+                for _annotation in _model_facing_annotations:
+                    if isinstance(result, str):
+                        result = f"{result}\n\n{_annotation}"
+                    elif isinstance(result, dict):
+                        result.setdefault("_additional_context", _annotation)
+                    else:
+                        result = {"value": result, "_additional_context": _annotation}
+
            return result
        except Exception as e:
            # Emit tool call end with error for exceptions that escape the retry loop
@@ -1132,8 +1226,9 @@ class ToolExecutionMixin:
        # tools_used, so without this the review policy always sees an empty
        # list and never runs. Consume the buffer so the next turn starts clean.
        if tools_used is None:
-            tools_used = list(getattr(self, "_turn_tools_used", []) or [])
-        self._turn_tools_used = []
+            tools_used = self._drain_turn_tools()
+        else:
+            self._drain_turn_tools()
        # Trigger AFTER_AGENT hook (only build the input if a hook is actually registered)
        from ..hooks import HookEvent
        if self._hook_runner.registry.has_hooks(HookEvent.AFTER_AGENT):
@@ -1189,8 +1284,9 @@ class ToolExecutionMixin:
        # Default tools_used from the per-turn buffer when the caller did not
        # pass it explicitly (issue #3037); mirrors the sync path.
        if tools_used is None:
-            tools_used = list(getattr(self, "_turn_tools_used", []) or [])
-        self._turn_tools_used = []
+            tools_used = self._drain_turn_tools()
+        else:
+            self._drain_turn_tools()
        # Trigger AFTER_AGENT hook (only build the input if a hook is actually registered)
        from ..hooks import HookEvent
        if self._hook_runner.registry.has_hooks(HookEvent.AFTER_AGENT):
@@ -1319,7 +1415,7 @@ class ToolExecutionMixin:
                try:
                    from ..runtime.tool_output_store import get_tool_output_store
                    from uuid import uuid4
-                    store = get_tool_output_store(getattr(self, '_run_id', None))
+                    store = get_tool_output_store(getattr(self, '_current_run_id', None))
                    # Add unique suffix to prevent collisions with repeated keys
                    unique_suffix = uuid4().hex[:8]
                    field_call_id = f"{tool_call_id}_{key}_{unique_suffix}" if tool_call_id else f"{tool_name}_{key}_{unique_suffix}"
@@ -1395,7 +1491,9 @@ class ToolExecutionMixin:
            # only gate the built-in DEFAULT_DANGEROUS_TOOLS and silently skip
            # registry-required tools.
            approval_registry = get_approval_registry()
-            registry_required = approval_registry.is_required(tool_name)
+            registry_required = approval_registry.is_required(
+                tool_name, getattr(self, 'name', None)
+            )
            # Check if tool needs approval based on multiple criteria
            needs_approval = (
                approve_all 
@@ -1409,7 +1507,7 @@ class ToolExecutionMixin:
                    tool_name=tool_name,
                    arguments=tool_args,
                    risk_level=(
-                        approval_registry.get_risk_level(tool_name)
+                        approval_registry.get_risk_level(tool_name, getattr(self, 'name', None))
                        or DEFAULT_DANGEROUS_TOOLS.get(tool_name, "medium")
                    ),
                    agent_name=getattr(self, 'name', None),
@@ -1474,21 +1572,19 @@ class ToolExecutionMixin:
                    return ApprovalDecision(approved=True, reason="Not a dangerous tool")
        else:
            # No approval backend configured. An explicit PermissionManager
-            # ``ask`` rule must still gate the call, so mark it required in the
-            # approval registry (idempotent) before delegating so the registry
-            # prompts instead of silently allowing.
-            if manager_forces_approval:
-                try:
-                    get_approval_registry().add_requirement(tool_name)
-                except Exception:  # noqa: BLE001
-                    pass
+            # ``ask`` rule must still gate the call. Rather than mutating shared
+            # registry state (which leaked onto other agents when this agent had
+            # no stable name), pass the intent per-call via ``force`` so the
+            # registry prompts for *this* call only without side effects.
            if is_async:
                return get_approval_registry().approve_async(
                    getattr(self, 'name', None), tool_name, tool_args,
+                    force=manager_forces_approval,
                )
            else:
                return get_approval_registry().approve_sync(
                    getattr(self, 'name', None), tool_name, tool_args,
+                    force=manager_forces_approval,
                )

    def _permission_manager_requires_approval(self, function_name) -> bool:
@@ -1527,7 +1623,9 @@ class ToolExecutionMixin:
        - ``PLAN``: read-only exploration → deny any tool not tagged read-only.
        - ``DONT_ASK``: auto-deny anything that would otherwise prompt for input
          (an explicit ``ask`` rule or a known dangerous tool).
-        - ``DEFAULT``/``ACCEPT_EDITS``/unset: defer (return ``None``).
+        - ``ACCEPT_EDITS``: auto-approve file edit/write tools; defer the rest so
+          non-edit prompts (shell exec, deletes, external tools) still apply.
+        - ``DEFAULT``/unset: defer (return ``None``).
        """
        mode = getattr(self, "_permission_mode", None)
        if mode is None:
@@ -1585,6 +1683,17 @@ class ToolExecutionMixin:
                ))
            return None

+        if mode == PermissionMode.ACCEPT_EDITS:
+            # Auto-approve file edit/write tools so edits flow without prompting,
+            # while deferring everything else (shell exec, deletes, external
+            # tools) to the normal approval flow so they still gate as usual.
+            if self._is_edit_tool(function_name):
+                return _wrap(ApprovalDecision(
+                    approved=True,
+                    reason=f"PermissionMode.ACCEPT_EDITS: auto-approved edit tool '{function_name}'",
+                ))
+            return None
+
        return None

    def _tool_would_prompt(self, function_name) -> bool:
@@ -1602,7 +1711,9 @@ class ToolExecutionMixin:
            if self._permission_manager_requires_approval(function_name):
                return True
            from ..approval import get_approval_registry
-            if get_approval_registry().is_required(function_name):
+            if get_approval_registry().is_required(
+                function_name, getattr(self, 'name', None)
+            ):
                return True
            from ..tools import get_registry as get_tool_registry
            if get_tool_registry().get_trust_level(function_name) == "external":
@@ -1629,6 +1740,23 @@ class ToolExecutionMixin:
        )
        return not any(marker in name for marker in write_markers)

+    @staticmethod
+    def _is_edit_tool(function_name) -> bool:
+        """Best-effort heuristic for whether a tool edits/writes a file.
+
+        Used by ``PermissionMode.ACCEPT_EDITS`` to auto-approve edit-class tools
+        (write/edit/append/create/save/patch/mkdir) while leaving destructive or
+        execution tools (delete/exec/shell/…) to the normal approval flow.
+        """
+        if not function_name:
+            return False
+        name = str(function_name).lower()
+        edit_markers = (
+            "write", "edit", "append", "create", "mkdir", "save",
+            "insert", "patch", "apply_patch",
+        )
+        return any(marker in name for marker in edit_markers)
+
    def _check_permission_manager_deny(self, function_name):
        """Return an error dict if the PermissionManager hard-denies the tool.

@@ -1694,12 +1822,14 @@ class ToolExecutionMixin:
            logging.warning(error_msg)
            return {"error": error_msg, "approval_denied": True}
        
-        from ..approval import get_approval_registry
-        get_approval_registry().mark_approved(function_name)
-        
        if decision.modified_args:
            arguments = decision.modified_args
            logging.info(f"Using modified arguments: {arguments}")
+
+        from ..approval import get_approval_registry
+        get_approval_registry().mark_approved(
+            function_name, arguments, agent_name=getattr(self, "name", None)
+        )
        return None, arguments

    async def _check_tool_approval_async(self, function_name, arguments):
@@ -1725,12 +1855,14 @@ class ToolExecutionMixin:
            logging.warning(error_msg)
            return {"error": error_msg, "approval_denied": True}
        
-        from ..approval import get_approval_registry
-        get_approval_registry().mark_approved(function_name)
-        
        if decision.modified_args:
            arguments = decision.modified_args
            logging.info(f"Using modified arguments: {arguments}")
+
+        from ..approval import get_approval_registry
+        get_approval_registry().mark_approved(
+            function_name, arguments, agent_name=getattr(self, "name", None)
+        )
        return None, arguments

    def _execute_tool_with_circuit_breaker(self, function_name, arguments):
@@ -1839,6 +1971,35 @@ class ToolExecutionMixin:
            raise last_exception
        return {"error": "Maximum retry attempts exceeded"}

+    @staticmethod
+    def _remove_circuit_breaker(breaker_name):
+        """Remove a circuit breaker entry from the process-global registry."""
+        try:
+            from ..tools.circuit_breaker import _get_global_registry
+        except Exception:
+            return
+        try:
+            _get_global_registry().remove(breaker_name)
+        except Exception:
+            pass
+
+    def _register_breaker_finalizer(self, breaker_name):
+        """Register a weakref finalizer so this agent's breaker entry is removed
+        the moment the agent is garbage-collected, even if close() is never called.
+        """
+        registered = self.__dict__.setdefault('_breaker_finalizer_names', set())
+        if breaker_name in registered:
+            return
+        registered.add(breaker_name)
+        try:
+            import weakref
+            finalizers = self.__dict__.setdefault('_breaker_finalizers', [])
+            finalizers.append(
+                weakref.finalize(self, self._remove_circuit_breaker, breaker_name)
+            )
+        except Exception:
+            pass
+
    def _execute_tool_with_circuit_breaker_impl(self, function_name, arguments):
        """Execute tool with circuit breaker protection (internal implementation).
        
@@ -1870,7 +2031,13 @@ class ToolExecutionMixin:
                graceful_degradation=True   # Return error instead of raising exception
            )
            breaker = get_circuit_breaker(breaker_name, config)
-            
+
+            # Ensure the registry entry is removed the moment this Agent is
+            # actually garbage-collected, regardless of whether close()/aclose()
+            # was ever called. This closes the CPython id-reuse window where a
+            # new Agent at the same address could inherit a stale OPEN breaker.
+            self._register_breaker_finalizer(breaker_name)
+
            # Execute tool through circuit breaker with failure detection wrapper
            def _tool_wrapper():
                result = self._execute_tool_impl(function_name, arguments)
@@ -2067,8 +2234,11 @@ class ToolExecutionMixin:
                func = tool
                break
        
-        if func is None:
-            # Check the global tool registry for plugins
+        if func is None and getattr(self, '_allow_global_tools', False):
+            # Check the process-global tool registry for plugins. Gated behind
+            # ToolConfig(allow_global_tools=True) so an agent is scoped strictly
+            # to its declared tools=[...] by default (safe by default) and cannot
+            # execute an @tool-decorated callable it was never given.
            try:
                from ..tools.registry import get_registry
                registry = get_registry()
@@ -2190,6 +2360,49 @@ class ToolExecutionMixin:
            return getattr(tool, '__name__', None)
        return None

+    def _resolve_model_facing_result(self, function_name, result):
+        """Return a tool's compact, model-facing view for ``result``, or ``None``.
+
+        Resolution order (first hit wins):
+
+        1. ``result.model_output`` — a ToolResult carrying its own compact view.
+        2. The producing tool's ``to_model_output(output)`` hook — set via
+           ``@tool(to_model_output=fn)`` or a ``BaseTool`` override.
+
+        The hook is invoked with the tool's raw output **value**, matching the
+        single ``BaseTool.to_model_output`` contract: if ``result`` is a
+        ``ToolResult`` the enclosed ``output`` is passed, otherwise ``result``
+        itself. ``None`` means the tool opted out, so the caller keeps today's
+        full stringification (fully backward-compatible).
+        """
+        try:
+            from ..tools.base import resolve_model_output
+            compact = resolve_model_output(result)
+            if compact is not None:
+                return compact
+        except Exception:
+            pass
+
+        # Unwrap to the raw output value so the hook receives the same payload
+        # BaseTool.safe_run passes (the ``output`` channel), keeping one contract.
+        hook_input = getattr(result, 'output', result)
+        try:
+            for name, tool in self._iter_active_named_tools():
+                if name != function_name:
+                    continue
+                hook = getattr(tool, 'to_model_output', None)
+                if callable(hook):
+                    try:
+                        return hook(hook_input)
+                    except Exception as e:
+                        logging.debug(
+                            f"to_model_output hook failed for '{function_name}': {e}"
+                        )
+                return None
+        except Exception:
+            pass
+        return None
+
    def _iter_active_named_tools(self):
        """Yield ``(name, tool)`` for every active tool.

@@ -330,17 +330,26 @@ async def _execute_with_agent_async(executor_agent, task_prompt, task, tools, st
        )


-def _build_execution_context(agents_instance, task_id):
+def _build_execution_context(agents_instance, task_id, skip_memory_init=False):
    """
    Build unified execution context for task execution (DRY helper).
    Eliminates duplication between sync/async execution paths.
+
+    Args:
+        skip_memory_init: When True, skip the synchronous ``initialize_memory()``
+            call. The async path (``aexecute_task``) already attempts
+            ``initialize_memory_async()`` beforehand, so this avoids blocking the
+            event loop on a synchronous ``Memory()`` construction (and a
+            duplicate backend attempt) if that async init failed.
    """
    from .protocols import ExecutionContext
    
    task = agents_instance.tasks[task_id]
    
-    # Initialize memory before task execution
-    if not task.memory:
+    # Initialize memory before task execution. The async path (aexecute_task)
+    # already attempts initialize_memory_async() and passes skip_memory_init=True
+    # so we never block the event loop on a synchronous Memory() construction.
+    if not task.memory and not skip_memory_init:
        task.memory = task.initialize_memory()

    executor_agent = task.agent
@@ -379,6 +388,18 @@ def _build_execution_context(agents_instance, task_id):

    # Build context first to include in task prompt
    context_text = ""
+    # Inter-task context / validation feedback assembled by the workflow process
+    # engine (Process._build_task_context) is stored on the task; fold it in so
+    # downstream/retried tasks actually see upstream output and rejection reasons.
+    extra_context = getattr(task, '_execution_context', None)
+    if extra_context:
+        context_text = extra_context
+        # NOTE: We intentionally do NOT clear _execution_context here. Task
+        # retries (guardrail/completion failures) re-enter this helper via the
+        # run_task/arun_task retry loops, and clearing would strip the upstream
+        # output + validation feedback the retry needs. The Process engine owns
+        # this field's lifecycle: it re-sets it before each task yield and resets
+        # every task's _execution_context to None before selecting the next task.
    if task.context:
        context_results = []  # Collect contexts then de-duplicate
        for context_item in task.context:
@@ -395,7 +416,11 @@ def _build_execution_context(agents_instance, task_id):
            for i, ctx in enumerate(unique_contexts):
                logger.debug(f"Context {i+1}: {ctx[:100]}...")
        context_separator = '\n\n'
-        context_text = context_separator.join(unique_contexts)
+        joined_contexts = context_separator.join(unique_contexts)
+        if context_text and joined_contexts:
+            context_text = context_text + context_separator + joined_contexts
+        elif joined_contexts:
+            context_text = joined_contexts
    
    # Build task prompt using DRY helper
    task_prompt = _prepare_task_prompt(task, task_description, context_text)
@@ -464,26 +489,59 @@ def _process_task_result(agents_instance, context, agent_output):
            except Exception as e:
                logger.warning(f"Warning: Could not clean output of task {task_id}: {e}")

+        json_parse_error = None
+        pydantic_parse_error = None
+
        if task.output_json:
            try:
                parsed = json.loads(cleaned)
                task_output.json_dict = parsed
                task_output.output_format = "JSON"
-            except Exception:
-                logger.warning(f"Warning: Could not parse output of task {task_id} as JSON")
+            except Exception as e:
+                json_parse_error = e
+                logger.warning(f"Warning: Could not parse output of task {task_id} as JSON: {e}")
                logger.debug(f"Output that failed JSON parsing: {agent_output}")

        if task.output_pydantic:
            try:
                parsed = json.loads(cleaned)
-                pyd_obj = task.output_pydantic(**parsed)
+                if hasattr(task.output_pydantic, "model_validate"):
+                    pyd_obj = task.output_pydantic.model_validate(parsed)
+                else:
+                    pyd_obj = task.output_pydantic(**parsed)
                task_output.pydantic = pyd_obj
                task_output.output_format = "Pydantic"
-            except Exception:
-                logger.warning(f"Warning: Could not parse output of task {task_id} as Pydantic Model")
+            except Exception as e:
+                pydantic_parse_error = e
+                schema_name = getattr(task.output_pydantic, "__name__", str(task.output_pydantic))
+                logger.warning(
+                    f"Warning: Could not parse output of task {task_id} as Pydantic Model "
+                    f"({schema_name}): {e}"
+                )
                logger.debug(f"Output that failed Pydantic parsing: {agent_output}")

        task.result = task_output
+
+        # Fail-closed: when structured output was requested but not produced,
+        # the task did not fulfil its contract. Surface it as a failed result so
+        # callers relying on TaskResult.success (and the retry loop, which uses
+        # completion_checker) do not treat freeform prose as a success.
+        if task.output_pydantic and task_output.pydantic is None:
+            schema_name = getattr(task.output_pydantic, "__name__", str(task.output_pydantic))
+            detail = f" ({pydantic_parse_error})" if pydantic_parse_error is not None else ""
+            return TaskResult(
+                task_output=task_output,
+                success=False,
+                error=f"Structured output validation failed for {schema_name}: could not parse agent output as the requested Pydantic model.{detail}",
+            )
+        if task.output_json and task_output.json_dict is None:
+            detail = f" ({json_parse_error})" if json_parse_error is not None else ""
+            return TaskResult(
+                task_output=task_output,
+                success=False,
+                error=f"Structured output validation failed: could not parse agent output as JSON.{detail}",
+            )
+
        return TaskResult(task_output=task_output, success=True)
    else:
        task.status = "failed"
@@ -814,6 +872,9 @@ class AgentTeam(SpawnAnnounceProtocol):
            _max_retries = 3
        self.completion_checker = _completion_checker if _completion_checker else self.default_completion_checker
        self.task_id_counter = 0
+        # Last user-supplied task id, tracked for hierarchical runs so the
+        # return path never surfaces the synthetic manager_task's output.
+        self._last_real_task_id = None
        self._task_id_lock = threading.Lock()  # Thread-safe task ID assignment
        self._state_lock = threading.Lock()  # Thread-safe state mutations
        self.verbose = _verbose
@@ -842,6 +903,11 @@ class AgentTeam(SpawnAnnounceProtocol):
        self._event_bus: Optional[EventBus] = None
        self._spawn_lock = threading.RLock()  # Thread-safe spawn operations (reentrant)
        self._team_id = str(uuid.uuid4())  # Unique team identifier
+        # Aggregate stream emitter (lazy). Fans in member agents' per-step
+        # StreamEventEmitter events, tagging each with the emitting agent's id,
+        # so a single consumer can attribute activity to a specific team member.
+        self.__stream_emitter = None
+        self.__stream_fanin_wired = False
        
        # Check for manager_llm in environment variable if not provided
        self.manager_llm = manager_llm or os.getenv('OPENAI_MODEL_NAME', 'gpt-4o-mini')
@@ -960,6 +1026,63 @@ class AgentTeam(SpawnAnnounceProtocol):
        except (ImportError, AttributeError):
            self._telemetry = None

+    @property
+    def stream_emitter(self):
+        """Aggregate ``StreamEventEmitter`` fanning in member agents' events.
+
+        Lazily created on first access. On creation it registers a forwarding
+        callback on each member agent's own ``stream_emitter`` so per-step
+        events (tool calls, text/reasoning deltas, retries, errors) surface on a
+        single team-level emitter, each tagged with the emitting agent's
+        ``agent_id``. This gives a single attach point (e.g. the CLI
+        ``--output stream-json`` bridge) parity with single-agent runs.
+
+        Zero-overhead when unused: nothing is wired unless this property is
+        accessed, and forwarding only tags ``agent_id`` when the source event
+        did not already carry one.
+        """
+        if self.__stream_emitter is None:
+            try:
+                from ..streaming.events import StreamEventEmitter
+            except ImportError:
+                return None
+            self.__stream_emitter = StreamEventEmitter()
+        if not self.__stream_fanin_wired:
+            self._wire_stream_fanin()
+        return self.__stream_emitter
+
+    def _wire_stream_fanin(self):
+        """Forward each member agent's stream events onto the team emitter.
+
+        Best-effort and idempotent: an agent whose emitter is unavailable is
+        skipped, and a forwarding callback is attached at most once per team.
+        """
+        team_emitter = self.__stream_emitter
+        if team_emitter is None:
+            return
+        self.__stream_fanin_wired = True
+        for agent in self.agents:
+            member_emitter = getattr(agent, "stream_emitter", None)
+            if member_emitter is None or not hasattr(member_emitter, "add_callback"):
+                continue
+            agent_id = getattr(agent, "agent_id", None) or getattr(agent, "display_name", None)
+            member_emitter.add_callback(self._make_fanin_callback(team_emitter, agent_id))
+
+    @staticmethod
+    def _make_fanin_callback(team_emitter, agent_id):
+        """Build a callback that re-emits an event on the team emitter."""
+        def _forward(event):
+            try:
+                if agent_id is not None and getattr(event, "agent_id", None) is None:
+                    try:
+                        event.agent_id = agent_id
+                    except (AttributeError, TypeError):
+                        pass
+                team_emitter.emit(event)
+            except Exception:
+                logger.debug("AgentTeam stream fan-in forward failed", exc_info=True)
+        return _forward
+
    def add_task(self, task):
        with self._task_id_lock:
            task_id = self.task_id_counter
@@ -968,6 +1091,26 @@ class AgentTeam(SpawnAnnounceProtocol):
            self.task_id_counter += 1
            return task_id

+    def _last_hierarchical_task_id(self):
+        """Return the last user-supplied task id before hierarchical injection.
+
+        The hierarchical process injects a synthetic ``manager_task`` that always
+        lands last in the insertion-ordered ``self.tasks`` dict. Snapshotting the
+        real task ids up front lets the return path surface the final delegated
+        task's result instead of the Manager's own generic answer.
+
+        A ``manager_task`` from a prior run of the same team can still be present
+        in ``self.tasks`` (it is not removed after a run), so it is explicitly
+        skipped here; otherwise a second ``.start()`` would return the previous
+        run's Manager output instead of the final user-task result.
+        """
+        for task_id in reversed(self.tasks):
+            task = self.tasks.get(task_id)
+            if getattr(task, "name", None) == "manager_task":
+                continue
+            return task_id
+        return None
+
    def clean_json_output(self, output: str) -> str:
        # NOTE: This method is duplicated in chat_mixin.ChatMixin.clean_json_output.
        # Keep both implementations in sync when modifying either.
@@ -1026,10 +1169,14 @@ class AgentTeam(SpawnAnnounceProtocol):
        return self._context_manager

    def default_completion_checker(self, task, agent_output):
-        if task.output_json and task.result and task.result.json_dict:
-            return True
-        if task.output_pydantic and task.result and task.result.pydantic:
-            return True
+        # Fail-closed for structured output: if a structured model was requested
+        # but not produced, the task is NOT complete. Returning False here drives
+        # the existing retry loop and, once retries are exhausted, leaves the task
+        # in a "failed" state instead of silently succeeding with freeform prose.
+        if task.output_json:
+            return task.result is not None and task.result.json_dict is not None
+        if task.output_pydantic:
+            return task.result is not None and task.result.pydantic is not None
        return len(agent_output.strip()) > 0

    async def aexecute_task(self, task_id):
@@ -1054,8 +1201,17 @@ class AgentTeam(SpawnAnnounceProtocol):
        if task.status == "not started":
            task.status = "in progress"

-        # Build execution context using DRY helper
-        context = _build_execution_context(self, task_id)
+        # Initialize memory asynchronously to avoid blocking the event loop on
+        # synchronous Memory() construction. The shared helper's own
+        # `if not task.memory:` guard makes this a safe no-op for the sync path.
+        if not task.memory:
+            await task.initialize_memory_async()
+
+        # Build execution context using DRY helper. skip_memory_init=True prevents
+        # the helper from falling back to the *synchronous* initialize_memory()
+        # (which would block the event loop and duplicate a failed backend attempt)
+        # when the async init above did not populate task.memory.
+        context = _build_execution_context(self, task_id, skip_memory_init=True)

        # Execute with agent using DRY helper
        agent_output = await _execute_with_agent_async(
@@ -1252,6 +1408,20 @@ class AgentTeam(SpawnAnnounceProtocol):
            task.status = "failed"  # Set failed status to match sync behavior
            logger.info(f"Task {task_id} failed after {task_max} retries.")

+    @staticmethod
+    async def _gather_with_isolation(coros):
+        """Gather async tasks with exception isolation.
+
+        Uses return_exceptions=True so a single failure does not orphan its
+        siblings (leaving them running in the background to mutate shared state).
+        The first exception is re-raised after all siblings have settled.
+        """
+        results = await asyncio.gather(*coros, return_exceptions=True)
+        for result in results:
+            if isinstance(result, BaseException):
+                raise result
+        return results
+
    async def arun_all_tasks(self):
        """Async version of run_all_tasks method"""
        process = Process(
@@ -1270,7 +1440,7 @@ class AgentTeam(SpawnAnnounceProtocol):
                else:
                    # If we encounter a sync task, we must wait for the previous async tasks to finish.
                    if tasks_to_run:
-                        await asyncio.gather(*tasks_to_run)
+                        await self._gather_with_isolation(tasks_to_run)
                        tasks_to_run = []
                    
                    # Run sync task in an executor to avoid blocking the event loop
@@ -1280,7 +1450,7 @@ class AgentTeam(SpawnAnnounceProtocol):
                    await loop.run_in_executor(None, copy_context_to_callable(lambda tid=task_id: self.run_task(tid)))

            if tasks_to_run:
-                await asyncio.gather(*tasks_to_run)
+                await self._gather_with_isolation(tasks_to_run)
                
        elif self.process == "sequential":
            async_tasks_to_run = []
@@ -1289,7 +1459,7 @@ class AgentTeam(SpawnAnnounceProtocol):
                """Execute all pending async tasks"""
                nonlocal async_tasks_to_run
                if async_tasks_to_run:
-                    await asyncio.gather(*async_tasks_to_run)
+                    await self._gather_with_isolation(async_tasks_to_run)
                    async_tasks_to_run = []
            
            async for task_id in process.asequential():
@@ -1308,6 +1478,12 @@ class AgentTeam(SpawnAnnounceProtocol):
            # Execute any remaining async tasks at the end
            await flush_async_tasks()
        elif self.process == "hierarchical":
+            # Snapshot the real (user-supplied) task ids before the hierarchical
+            # generator injects its synthetic manager_task. The manager_task is
+            # always added last (highest id), so relying on dict-insertion order
+            # in the return path would surface the Manager's own generic answer
+            # instead of the final delegated task's result.
+            self._last_real_task_id = self._last_hierarchical_task_id()
            async for task_id in process.ahierarchical():
                if isinstance(task_id, Task):
                    task_id = self.add_task(task_id)
@@ -1350,10 +1526,14 @@ class AgentTeam(SpawnAnnounceProtocol):
        
        # By default, return only the final agent's response
        if not return_dict:
-            # Get the last task (assuming sequential processing)
-            task_ids = list(self.tasks.keys())
-            if task_ids:
-                last_task_id = task_ids[-1]
+            # Prefer the tracked last real task id (set by hierarchical runs so
+            # the synthetic manager_task never masks the real final result);
+            # otherwise fall back to the last task in insertion order.
+            last_task_id = getattr(self, "_last_real_task_id", None)
+            if last_task_id is None:
+                task_ids = list(self.tasks.keys())
+                last_task_id = task_ids[-1] if task_ids else None
+            if last_task_id is not None:
                last_result = self.get_task_result(last_task_id)
                if last_result:
                    return last_result.raw
@@ -1448,7 +1628,13 @@ class AgentTeam(SpawnAnnounceProtocol):
                    except Exception as e:
                        logger.error(f"Error executing memory callback for task {task_id}: {e}")
                        logger.exception(e)
-                            
+                        # Respect task failure policies - re-raise if configured
+                        # (mirrors arun_task so sync/async surfaces behave identically)
+                        if hasattr(task, 'fail_on_callback_error') and task.fail_on_callback_error:
+                            raise
+                        if hasattr(task, 'fail_on_memory_error') and task.fail_on_memory_error:
+                            raise
+
                    self.save_output_to_file(task, task_output)

                    # Call on_task_complete callback (shared with arun_task)
@@ -1495,6 +1681,10 @@ class AgentTeam(SpawnAnnounceProtocol):
            for task_id in process.sequential():
                self.run_task(task_id)
        elif self.process == "hierarchical":
+            # See arun_all_tasks: capture the last real task id before the
+            # synthetic manager_task is injected so the return path doesn't
+            # surface the Manager's own generic output.
+            self._last_real_task_id = self._last_hierarchical_task_id()
            for task_id in process.hierarchical():
                if isinstance(task_id, Task):
                    task_id = self.add_task(task_id)
@@ -1731,9 +1921,14 @@ class AgentTeam(SpawnAnnounceProtocol):
        
        # By default, return only the final agent's response
        if not return_dict:
-            task_ids = list(self.tasks.keys())
-            if task_ids:
-                last_task_id = task_ids[-1]
+            # Prefer the tracked last real task id (set by hierarchical runs so
+            # the synthetic manager_task never masks the real final result);
+            # otherwise fall back to the last task in insertion order.
+            last_task_id = getattr(self, "_last_real_task_id", None)
+            if last_task_id is None:
+                task_ids = list(self.tasks.keys())
+                last_task_id = task_ids[-1] if task_ids else None
+            if last_task_id is not None:
                last_result = self.get_task_result(last_task_id)
                if last_result:
                    return last_result.raw
@@ -1754,6 +1949,170 @@ class AgentTeam(SpawnAnnounceProtocol):
        # Always run silently - no verbose output
        return self.start(content=content, return_dict=return_dict, output="silent", **kwargs)

+    def _snapshot_task_state(self):
+        """Snapshot per-task run state so a batch can restore it afterwards.
+
+        Captures the fields that ``run_task``/``arun_task`` mutate during a run
+        (``status``, ``result``, ``retry_count``) plus caller-defined
+        ``variables``, keeping the public Task API backward-compatible.
+        """
+        snapshot = {}
+        for task_id, task in self.tasks.items():
+            snapshot[task_id] = {
+                "status": getattr(task, "status", None),
+                "result": getattr(task, "result", None),
+                "retry_count": getattr(task, "retry_count", None),
+                "variables": getattr(task, "variables", None),
+            }
+        return snapshot
+
+    def _reset_task_state_for_item(self):
+        """Reset per-task run state before each batch item executes.
+
+        Without this, ``run_task``/``arun_task`` see ``status == "completed"``
+        from the previous item and skip execution, returning stale results.
+        Clearing ``variables`` lets the current item's global ``variables``
+        re-propagate (see ``_run_task_start_hook``).
+        """
+        for task in self.tasks.values():
+            task.status = "not started"
+            task.result = None
+            if hasattr(task, "retry_count"):
+                task.retry_count = 0
+            task.variables = {}
+
+    def _restore_task_state(self, snapshot):
+        """Restore per-task run state captured by ``_snapshot_task_state``."""
+        for task_id, state in snapshot.items():
+            task = self.tasks.get(task_id)
+            if task is None:
+                continue
+            task.status = state["status"]
+            task.result = state["result"]
+            if state["retry_count"] is not None:
+                task.retry_count = state["retry_count"]
+            task.variables = state["variables"]
+
+    def _build_batch_result(self, batch_id, items):
+        """Aggregate per-item results into a batch summary dict.
+
+        ``token_usage_total`` is the session-level summary from the shared token
+        collector (cumulative, not batch-scoped) — kept lightweight; use
+        per-item outputs for finer accounting.
+        """
+        succeeded = sum(1 for item in items if item["success"])
+        return {
+            "batch_id": batch_id,
+            "items": items,
+            "outputs": [item["output"] for item in items],
+            "succeeded": succeeded,
+            "failed": len(items) - succeeded,
+            "total": len(items),
+            "token_usage_total": self.get_token_usage_summary(),
+        }
+
+    @staticmethod
+    def _validate_batch_input(item_input, index):
+        """Coerce/validate a single batch input into a dict of variables."""
+        if item_input is None:
+            return {}
+        if not isinstance(item_input, dict):
+            raise ValueError(
+                f"inputs[{index}] must be a dict of variables, got "
+                f"{type(item_input).__name__}"
+            )
+        return item_input
+
+    def start_for_each(
+        self,
+        inputs,
+        *,
+        on_error="continue",
+        output="silent",
+        **kwargs,
+    ):
+        """Run this team once per input dict, interpolating ``{{key}}`` placeholders.
+
+        Each input dict is applied as per-run ``variables`` (existing
+        ``{{placeholder}}`` interpolation in task descriptions), so the original
+        task templates are never permanently mutated.
+
+        Args:
+            inputs: List of dicts; each runs the team once with those variables.
+            on_error: "continue" (default) collects errors per item and keeps
+                going; "fail_fast" re-raises on the first failing item.
+            output: Output preset forwarded to ``start`` (default "silent").
+            **kwargs: Additional arguments forwarded to ``start``.
+
+        Returns:
+            dict with ``batch_id``, ``items`` (per-item ``index``/``input``/
+            ``success``/``output``/``error``), ``outputs``, ``succeeded``,
+            ``failed``, ``total`` and ``token_usage_total``.
+        """
+        if on_error not in ("continue", "fail_fast"):
+            raise ValueError("on_error must be 'continue' or 'fail_fast'")
+
+        batch_id = f"batch_{uuid.uuid4().hex[:12]}"
+        saved_variables = self.variables
+        task_snapshot = self._snapshot_task_state()
+        items = []
+        try:
+            for index, item_input in enumerate(inputs):
+                result = {"index": index, "input": item_input, "success": False,
+                          "output": None, "error": None}
+                try:
+                    item_vars = self._validate_batch_input(item_input, index)
+                    self.variables = {**saved_variables, **item_vars}
+                    self._reset_task_state_for_item()
+                    result["output"] = self.start(output=output, **kwargs)
+                    result["success"] = True
+                except Exception as exc:  # noqa: BLE001
+                    if on_error == "fail_fast":
+                        raise
+                    result["error"] = str(exc)
+                items.append(result)
+        finally:
+            self.variables = saved_variables
+            self._restore_task_state(task_snapshot)
+
+        return self._build_batch_result(batch_id, items)
+
+    async def astart_for_each(
+        self,
+        inputs,
+        *,
+        on_error="continue",
+        **kwargs,
+    ):
+        """Async twin of :meth:`start_for_each` (sequential per-item execution)."""
+        if on_error not in ("continue", "fail_fast"):
+            raise ValueError("on_error must be 'continue' or 'fail_fast'")
+
+        batch_id = f"batch_{uuid.uuid4().hex[:12]}"
+        saved_variables = self.variables
+        task_snapshot = self._snapshot_task_state()
+        items = []
+        try:
+            for index, item_input in enumerate(inputs):
+                result = {"index": index, "input": item_input, "success": False,
+                          "output": None, "error": None}
+                try:
+                    item_vars = self._validate_batch_input(item_input, index)
+                    self.variables = {**saved_variables, **item_vars}
+                    self._reset_task_state_for_item()
+                    result["output"] = await self.astart(**kwargs)
+                    result["success"] = True
+                except Exception as exc:  # noqa: BLE001
+                    if on_error == "fail_fast":
+                        raise
+                    result["error"] = str(exc)
+                items.append(result)
+        finally:
+            self.variables = saved_variables
+            self._restore_task_state(task_snapshot)
+
+        return self._build_batch_result(batch_id, items)
+
    def set_state(self, key: str, value: Any) -> None:
        """Set a state value"""
        with self._state_lock:
@@ -1830,38 +2189,100 @@ class AgentTeam(SpawnAnnounceProtocol):
            
            return self._state[key]
    
-    def save_session_state(self, session_id: str, include_memory: bool = True) -> None:
-        """Save current state to memory for session persistence"""
-        if self.shared_memory and include_memory:
-            state_data = {
-                "session_id": session_id,
-                "user_id": self.user_id,
-                "run_id": self.run_id,
-                "state": self._state,
-                "agents": [agent.display_name for agent in self.agents],
-                "process": self.process
-            }
-            self.shared_memory.store_short_term(
-                text=f"Session state for {session_id}",
-                metadata={
-                    "type": "session_state",
-                    "session_id": session_id,
-                    "user_id": self.user_id,
-                    "state_data": state_data
-                }
+    def _team_state_payload(self, session_id: str) -> Dict[str, Any]:
+        """Build the serialisable team-state payload for durable persistence."""
+        with self._state_lock:
+            state_copy = dict(self._state)
+        return {
+            "session_id": session_id,
+            "user_id": self.user_id,
+            "run_id": self.run_id,
+            "state": state_copy,
+            "agents": [agent.display_name for agent in self.agents],
+            "process": self.process,
+        }
+
+    def save_session_state(self, session_id: str, include_memory: bool = True) -> bool:
+        """Persist team session state for deterministic resume (Issue #3635).
+
+        Writes the shared team ``_state`` (plus run bookkeeping) to the durable,
+        project-scoped ``SessionStore`` — the same store single ``Agent`` resume
+        uses — keyed deterministically by ``session_id``. This gives multi-agent
+        runs the same locked, atomic, memory-independent continuity as a single
+        agent: it works even with ``memory=False``.
+
+        ``shared_memory`` is kept as an *optional enrichment* (not a gate) so
+        legacy semantic-recall lookups still find the state when memory is on.
+
+        Returns ``True`` when the durable write succeeded, ``False`` otherwise,
+        so callers can tell whether a resumable state actually reached disk.
+        """
+        state_data = self._team_state_payload(session_id)
+
+        # Primary, durable path: SessionStore (locked, atomic, memory-independent).
+        durable_saved = False
+        try:
+            from ..session.store import get_default_session_store
+            durable_saved = bool(
+                get_default_session_store().update_session_metadata(
+                    session_id, team_session_state=state_data
+                )
            )
-    
+            if not durable_saved:
+                logger.warning(
+                    f"Durable team session save reported no write for {session_id}"
+                )
+        except Exception as e:  # never fail a completed run on save
+            logger.warning(f"Durable team session save failed for {session_id}: {e}")
+
+        # Optional enrichment: mirror into shared memory for semantic recall.
+        if self.shared_memory and include_memory:
+            try:
+                self.shared_memory.store_short_term(
+                    text=f"Session state for {session_id}",
+                    metadata={
+                        "type": "session_state",
+                        "session_id": session_id,
+                        "user_id": self.user_id,
+                        "state_data": state_data,
+                    },
+                )
+            except Exception as e:
+                logger.debug(f"Shared-memory session enrichment failed: {e}")
+
+        return durable_saved
+
    def restore_session_state(self, session_id: str) -> bool:
-        """Restore state from memory for session persistence. Returns True if restored."""
+        """Restore team session state for deterministic resume. Returns True if restored.
+
+        Reads first from the durable ``SessionStore`` keyed by ``session_id``
+        (no fuzzy search, no memory requirement). Falls back to the legacy
+        ``shared_memory`` semantic lookup only for sessions written before this
+        durable path existed, preserving backward compatibility.
+        """
+        # Primary, durable path: SessionStore lookup by exact session_id.
+        try:
+            from ..session.store import get_default_session_store
+            store = get_default_session_store()
+            if store.session_exists(session_id):
+                metadata = store.get_session(session_id).metadata or {}
+                state_data = metadata.get("team_session_state")
+                if isinstance(state_data, dict) and "state" in state_data:
+                    with self._state_lock:
+                        self._state.update(state_data["state"])
+                    return True
+        except Exception as e:
+            logger.debug(f"Durable team session restore failed for {session_id}: {e}")
+
+        # Legacy fallback: shared-memory semantic lookup (pre-#3635 sessions).
        if not self.shared_memory:
            return False
-        
-        # Use metadata-based search for better SQLite compatibility
+
        results = self.shared_memory.search_short_term(
-            query=f"type:session_state",
+            query="type:session_state",
            limit=10  # Get more results to filter by session_id
        )
-        
+
        # Filter results by session_id in metadata
        for result in results:
            metadata = result.get("metadata", {})
@@ -1952,14 +2373,17 @@ class AgentTeam(SpawnAnnounceProtocol):
        """
        Launch all agents as a single API endpoint (HTTP) or an MCP server. 
        In HTTP mode, the endpoint accepts a query and processes it through all agents in sequence.
-        In MCP mode, an MCP server is started, exposing a tool to run the agent workflow.
+        In MCP mode, serving is delegated to the ``praisonai-mcp`` agent adapter
+        (``serve_agents``), publishing ``ask_{agent_name}`` per agent plus
+        ``list_agents`` — the same path used by ``Agent.launch(protocol="mcp")``.
        
        Args:
-            path: API endpoint path (default: '/agents') for HTTP, or base path for MCP.
+            path: API endpoint path (default: '/agents') for HTTP. Ignored in MCP mode.
            port: Server port (default: 8000)
            host: Server host (default: '0.0.0.0')
            debug: Enable debug mode for uvicorn (default: False)
-            protocol: "http" to launch as FastAPI, "mcp" to launch as MCP server.
+            protocol: "http" to launch as FastAPI, "mcp" to serve over MCP via
+                ``praisonai-mcp`` (install with ``pip install praisonai-mcp``).
            
        Returns:
            None
@@ -2222,144 +2646,26 @@ class AgentTeam(SpawnAnnounceProtocol):
                logging.warning("No agents to launch for MCP mode. Add agents to the Agents instance first.")
                return

+            # Delegate to the praisonai-mcp agent adapter so multi-agent MCP
+            # serving shares one blessed entry point with the single-agent
+            # Agent.launch(protocol="mcp") path (both go through serve_agents).
+            # praisonai-mcp is an optional dependency imported lazily so core
+            # keeps no hard dependency on it.
            try:
-                import uvicorn
-                from mcp.server.fastmcp import FastMCP
-                from mcp.server.sse import SseServerTransport
-                from starlette.applications import Starlette
-                from starlette.requests import Request
-                from starlette.routing import Mount, Route
-                # from mcp.server import Server as MCPServer # Not directly needed if using FastMCP's server
-                import threading
-                import time
-                import inspect
-                import asyncio
-                # logging is already imported at the module level
-                
-            except ImportError as e:
-                missing_module = str(e).split("No module named '")[-1].rstrip("'")
-                display_error(f"Missing dependency: {missing_module}. Required for launch() method with MCP mode.")
-                logging.error(f"Missing dependency: {missing_module}. Required for launch() method with MCP mode.")
-                print(f"\nTo add MCP capabilities, install the required dependencies:")
-                print(f"pip install {missing_module} mcp praison-mcp starlette uvicorn")
-                print("\nOr install all MCP dependencies with relevant packages.")
+                from praisonai_mcp import serve_agents
+
+                # Keep the call inside the ImportError guard: serve_agents()
+                # lazily imports its transport backend, so a praisonai-mcp
+                # installed without its optional transport extras surfaces the
+                # missing dependency here rather than at the import line above.
+                # Handling it in one place yields a single actionable install
+                # message instead of an uncaught traceback.
+                return serve_agents(self.agents, host=host, port=port)
+            except ImportError:
+                display_error("MCP serving requires the 'praisonai-mcp' package.")
+                logging.error("MCP serving requires the 'praisonai-mcp' package.")
+                print("\nTo add MCP capabilities, install: pip install praisonai-mcp")
                return None
-
-            mcp_instance = FastMCP("praisonai_workflow_mcp_server")
-
-            # Determine the MCP tool name for the workflow based on self.name
-            actual_mcp_tool_name = (f"execute_{self.name.lower().replace(' ', '_').replace('-', '_')}_workflow" if self.name 
-                                    else "execute_workflow")
-
-            @mcp_instance.tool(name=actual_mcp_tool_name)
-            async def execute_workflow_tool(query: str) -> str: # Renamed for clarity
-                """Executes the defined agent workflow with the given query."""
-                logging.info(f"MCP tool '{actual_mcp_tool_name}' called with query: {query}")
-                current_input = query
-                final_response = "No agents in workflow or workflow did not produce a final response."
-
-                for agent_instance in self.agents:
-                    try:
-                        logging.debug(f"Processing with agent: {agent_instance.display_name}")
-                        if hasattr(agent_instance, 'achat') and asyncio.iscoroutinefunction(agent_instance.achat):
-                            response = await agent_instance.achat(current_input, tools=agent_instance.tools, task_name=None, task_description=None, task_id=None)
-                        elif hasattr(agent_instance, 'chat'): # Fallback to sync chat if achat not suitable
-                            # Use copy_context_to_callable to propagate contextvars (needed for trace emission)
-                            from ..trace.context_events import copy_context_to_callable
-                            loop = asyncio.get_running_loop()
-                            response = await loop.run_in_executor(None, copy_context_to_callable(lambda ci=current_input: agent_instance.chat(ci, tools=agent_instance.tools)))
-                        else:
-                            logging.warning(f"Agent {agent_instance.display_name} has no suitable chat or achat method.")
-                            response = f"Error: Agent {agent_instance.display_name} has no callable chat method."
-                        
-                        current_input = response if response is not None else "Agent returned no response."
-                        final_response = current_input # Keep track of the last valid response
-                        logging.debug(f"Agent {agent_instance.display_name} responded. Current intermediate output: {current_input}")
-
-                    except Exception as e:
-                        logging.error(f"Error during agent {agent_instance.display_name} execution in MCP workflow: {str(e)}", exc_info=True)
-                        current_input = f"Error from agent {agent_instance.display_name}: {str(e)}"
-                        final_response = current_input # Update final response to show error
-                        # Optionally break or continue based on desired error handling for the workflow
-                        # For now, we continue, and the error is passed to the next agent or returned.
-                
-                logging.info(f"MCP tool '{actual_mcp_tool_name}' completed. Final response: {final_response}")
-                return final_response
-
-            base_mcp_path = path.rstrip('/')
-            sse_mcp_path = f"{base_mcp_path}/sse"
-            messages_mcp_path_prefix = f"{base_mcp_path}/messages"
-            if not messages_mcp_path_prefix.endswith('/'):
-                messages_mcp_path_prefix += '/'
-
-            sse_transport_mcp = SseServerTransport(messages_mcp_path_prefix)
-
-            async def handle_mcp_sse_connection(request: Request) -> None:
-                logging.debug(f"MCP SSE connection request from {request.client} for path {request.url.path}")
-                async with sse_transport_mcp.connect_sse(
-                        request.scope, request.receive, request._send,
-                ) as (read_stream, write_stream):
-                    await mcp_instance._mcp_server.run(
-                        read_stream, write_stream, mcp_instance._mcp_server.create_initialization_options(),
-                    )
-            
-            starlette_mcp_app = Starlette(
-                debug=debug,
-                routes=[
-                    Route(sse_mcp_path, endpoint=handle_mcp_sse_connection),
-                    Mount(messages_mcp_path_prefix, app=sse_transport_mcp.handle_post_message),
-                ],
-            )
-
-            print(f"🚀 Agents MCP Workflow server starting on http://{host}:{port}")
-            print(f"📡 MCP SSE endpoint available at {sse_mcp_path}")
-            print(f"📢 MCP messages post to {messages_mcp_path_prefix}")
-            # Instead of trying to extract tool names, hardcode the known tool name
-            mcp_tool_names = [actual_mcp_tool_name]  # Use the determined dynamic tool name
-            print(f"🛠️ Available MCP tools: {', '.join(mcp_tool_names)}")
-            agent_names_in_workflow = ", ".join([a.display_name for a in self.agents])
-            print(f"🔄 Agents in MCP workflow: {agent_names_in_workflow}")
-
-            def run_praison_mcp_server():
-                try:
-                    uvicorn.run(starlette_mcp_app, host=host, port=port, log_level="debug" if debug else "info")
-                except Exception as e:
-                    logging.error(f"Error starting Agents MCP server: {str(e)}", exc_info=True)
-                    print(f"❌ Error starting Agents MCP server: {str(e)}")
-
-            mcp_server_thread = threading.Thread(target=run_praison_mcp_server, daemon=True)
-            mcp_server_thread.start()
-            time.sleep(0.5) 
-
-            import inspect 
-            stack = inspect.stack()
-            if len(stack) > 1 and stack[1].filename.endswith('.py'):
-                caller_frame = stack[1]
-                caller_line = caller_frame.lineno
-                try:
-                    with open(caller_frame.filename, 'r') as f:
-                        lines = f.readlines()
-                    has_more_launches = False
-                    for line_content in lines[caller_line:]:
-                        if '.launch(' in line_content and not line_content.strip().startswith('#'):
-                            has_more_launches = True
-                            break
-                    if not has_more_launches:
-                        try:
-                            print("\nAgents MCP server running. Press Ctrl+C to stop.")
-                            while True:
-                                time.sleep(1)
-                        except KeyboardInterrupt:
-                            print("\nAgents MCP Server stopped")
-                except Exception as e:
-                    logging.error(f"Error in Agents MCP launch detection: {e}")
-                    try:
-                        print("\nKeeping Agents MCP server alive. Press Ctrl+C to stop.")
-                        while True:
-                            time.sleep(1)
-                    except KeyboardInterrupt:
-                        print("\nAgents MCP Server stopped")
-            return None
        else:
            display_error(f"Invalid protocol: {protocol}. Choose 'http' or 'mcp'.")
            return None
@@ -17,7 +17,6 @@ Usage:
    result = auto_rag.chat("Hello!")  # Skips retrieval
 """

-import logging
 from praisonaiagents._logging import get_logger
 import time
 from dataclasses import dataclass, field
@@ -5,7 +5,6 @@ Provides delegation primitives for spawning subagents with scoped permissions
 and context. Inspired by Gemini CLI's delegate-to-agent pattern.
 """

-import logging
 from praisonaiagents._logging import get_logger
 import asyncio
 import warnings
@@ -141,6 +140,7 @@ class SubagentDelegator:
        
        # State
        self._tasks: Dict[str, DelegationTask] = {}
+        self._running_asyncio_tasks: Dict[str, "asyncio.Task"] = {}
        self._running_count: int = 0
        self._total_count: int = 0
        self._task_counter: int = 0
@@ -221,9 +221,37 @@ class SubagentDelegator:
        self._tasks[task_id] = task
        self._total_count += 1
        
-        # Execute with concurrency control
+        # Execute with concurrency control. Wrap in a real asyncio.Task so
+        # cancel_task/cancel_all can actually propagate cancellation to the
+        # awaited subagent coroutine instead of only flipping a status enum.
        async with self._get_semaphore():
-            return await self._execute_task(task)
+            # If cancelled while queued on the semaphore, don't start the work.
+            if task.status == DelegationStatus.CANCELLED:
+                return DelegationResult(
+                    task_id=task.task_id,
+                    agent_name=task.agent_name,
+                    success=False,
+                    error="Task was cancelled",
+                )
+            exec_task = asyncio.ensure_future(self._execute_task(task))
+            self._running_asyncio_tasks[task_id] = exec_task
+            try:
+                return await exec_task
+            except asyncio.CancelledError:
+                # Distinguish a delegator-initiated cancel (via cancel_task/cancel_all,
+                # which sets status=CANCELLED) from an external/cooperative cancel of
+                # the caller. Only the former is swallowed into a result; an external
+                # cancel must propagate so wait_for/shutdown behave correctly.
+                if task.status == DelegationStatus.CANCELLED:
+                    return DelegationResult(
+                        task_id=task.task_id,
+                        agent_name=task.agent_name,
+                        success=False,
+                        error="Task was cancelled",
+                    )
+                raise
+            finally:
+                self._running_asyncio_tasks.pop(task_id, None)
    
    async def delegate_parallel(
        self,
@@ -283,14 +311,25 @@ class SubagentDelegator:
            True if task was cancelled
        """
        task = self._tasks.get(task_id)
-        if not task:
+        # Only terminal tasks are un-cancellable; PENDING/RUNNING can be cancelled.
+        _terminal = (
+            DelegationStatus.COMPLETED,
+            DelegationStatus.FAILED,
+            DelegationStatus.CANCELLED,
+            DelegationStatus.TIMEOUT,
+        )
+        if not task or task.status in _terminal:
            return False
        
-        if task.status == DelegationStatus.RUNNING:
-            task.status = DelegationStatus.CANCELLED
-            return True
+        # Mark cancelled first so a PENDING task (still waiting on the semaphore)
+        # or a RUNNING coroutine both observe CANCELLED and refuse to complete.
+        task.status = DelegationStatus.CANCELLED
        
-        return False
+        # Propagate cancellation to the actual coroutine if it is already running.
+        asyncio_task = self._running_asyncio_tasks.get(task_id)
+        if asyncio_task is not None:
+            asyncio_task.cancel()
+        return True
    
    async def cancel_all(self) -> int:
        """
@@ -300,9 +339,8 @@ class SubagentDelegator:
            Number of tasks cancelled
        """
        cancelled = 0
-        for task in self._tasks.values():
-            if task.status == DelegationStatus.RUNNING:
-                task.status = DelegationStatus.CANCELLED
+        for task_id in list(self._tasks.keys()):
+            if await self.cancel_task(task_id):
                cancelled += 1
        return cancelled
    
@@ -338,6 +376,15 @@ class SubagentDelegator:
        import time
        start_time = time.time()
        
+        # A cancel may have landed between scheduling and execution; honour it.
+        if task.status == DelegationStatus.CANCELLED:
+            return DelegationResult(
+                task_id=task.task_id,
+                agent_name=task.agent_name,
+                success=False,
+                error="Task was cancelled",
+            )
+        
        task.status = DelegationStatus.RUNNING
        self._running_count += 1
        
@@ -357,7 +404,9 @@ class SubagentDelegator:
                    timeout=task.timeout_seconds,
                )
                task.result = result
-                task.status = DelegationStatus.COMPLETED
+                # Don't clobber a cancellation that landed while we were running.
+                if task.status != DelegationStatus.CANCELLED:
+                    task.status = DelegationStatus.COMPLETED
                
            except asyncio.TimeoutError:
                task.status = DelegationStatus.TIMEOUT
@@ -31,6 +31,7 @@ from __future__ import annotations

 import asyncio
 import contextvars
+import inspect
 import json
 import logging
 from praisonaiagents._logging import get_logger
@@ -96,11 +97,19 @@ def get_approval_callback() -> Optional[Callable]:
    """Get the current approval callback function (legacy API)."""
    return approval_callback

-def mark_approved(tool_name: str) -> None:
-    get_approval_registry().mark_approved(tool_name)
+def mark_approved(
+    tool_name: str,
+    arguments: Optional[Dict] = None,
+    agent_name: Optional[str] = None,
+) -> None:
+    get_approval_registry().mark_approved(tool_name, arguments, agent_name)

-def is_already_approved(tool_name: str) -> bool:
-    return get_approval_registry().is_already_approved(tool_name)
+def is_already_approved(
+    tool_name: str,
+    arguments: Optional[Dict] = None,
+    agent_name: Optional[str] = None,
+) -> bool:
+    return get_approval_registry().is_already_approved(tool_name, arguments, agent_name)

 def is_yaml_approved(tool_name: str) -> bool:
    return get_approval_registry().is_yaml_approved(tool_name)
@@ -166,6 +175,29 @@ async def request_approval(function_name: str, arguments: Dict) -> ApprovalDecis

 RiskLevel = Literal["critical", "high", "medium", "low"]

+
+def _bind_call_args(func: Callable, args: tuple, kwargs: Dict) -> Dict:
+    """Normalise a call's positional + keyword args into a single dict.
+
+    The approval cache is keyed by the tool's arguments, so a directly-invoked
+    ``@require_approval`` tool must reduce positional args to the same named
+    form the cache uses — otherwise ``read_file("/a")`` and ``read_file("/b")``
+    would share the empty-argument key and one approval would unlock the other.
+
+    Falls back to a shallow merge of ``kwargs`` plus an ``__args__`` tuple when
+    the signature cannot be bound (e.g. C-implemented callables), so distinct
+    positional calls still produce distinct keys instead of collapsing.
+    """
+    try:
+        bound = inspect.signature(func).bind_partial(*args, **kwargs)
+        return dict(bound.arguments)
+    except (TypeError, ValueError):
+        merged = dict(kwargs)
+        if args:
+            merged["__args__"] = args
+        return merged
+
+
 def require_approval(risk_level: RiskLevel = "high"):
    """Decorator to mark a tool as requiring human approval."""
    def decorator(func):
@@ -177,13 +209,18 @@ def require_approval(risk_level: RiskLevel = "high"):

        @wraps(func)
        def wrapper(*args, **kwargs):
-            if is_already_approved(tool_name):
+            # Bind positional args into a normalized dict so the approval key
+            # reflects the *actual* call. Without this, positional-only calls
+            # (e.g. read_file("/etc/passwd")) would all collapse to the same
+            # empty-argument key, letting one approval unlock any later value.
+            approval_args = _bind_call_args(func, args, kwargs)
+            if is_already_approved(tool_name, approval_args):
                return func(*args, **kwargs)
            if is_yaml_approved(tool_name):
-                mark_approved(tool_name)
+                mark_approved(tool_name, approval_args)
                return func(*args, **kwargs)
            if is_env_auto_approve():
-                mark_approved(tool_name)
+                mark_approved(tool_name, approval_args)
                return func(*args, **kwargs)
            try:
                from ..utils.async_bridge import is_async_context, run_coroutine_from_any_context
@@ -196,32 +233,35 @@ def require_approval(risk_level: RiskLevel = "high"):
                    )
                else:
                    # Safe to run async approval using registry
-                    decision = run_coroutine_from_any_context(request_approval(tool_name, kwargs))
+                    decision = run_coroutine_from_any_context(request_approval(tool_name, approval_args))
            except Exception as e:
                logging.warning(f"Approval request failed: {e}", exc_info=True)
                # Fail closed - do not fall back to console
                raise PermissionError(f"Approval request failed for {tool_name}: {e}") from e
            if not decision.approved:
                raise PermissionError(f"Execution of {tool_name} denied: {decision.reason}")
-            mark_approved(tool_name)
            kwargs.update(decision.modified_args)
+            approval_args.update(decision.modified_args)
+            mark_approved(tool_name, approval_args)
            return func(*args, **kwargs)

        @wraps(func)
        async def async_wrapper(*args, **kwargs):
-            if is_already_approved(tool_name):
+            approval_args = _bind_call_args(func, args, kwargs)
+            if is_already_approved(tool_name, approval_args):
                return await func(*args, **kwargs)
            if is_yaml_approved(tool_name):
-                mark_approved(tool_name)
+                mark_approved(tool_name, approval_args)
                return await func(*args, **kwargs)
            if is_env_auto_approve():
-                mark_approved(tool_name)
+                mark_approved(tool_name, approval_args)
                return await func(*args, **kwargs)
-            decision = await request_approval(tool_name, kwargs)
+            decision = await request_approval(tool_name, approval_args)
            if not decision.approved:
                raise PermissionError(f"Execution of {tool_name} denied: {decision.reason}")
-            mark_approved(tool_name)
            kwargs.update(decision.modified_args)
+            approval_args.update(decision.modified_args)
+            mark_approved(tool_name, approval_args)
            return await func(*args, **kwargs)

        if asyncio.iscoroutinefunction(func):
@@ -11,7 +11,6 @@ Provides lightweight backends that ship with the core SDK:
 from __future__ import annotations

 import asyncio
-import logging
 from praisonaiagents._logging import get_logger
 from typing import Any

@@ -18,9 +18,6 @@ from __future__ import annotations

 import asyncio
 import contextvars
-import hashlib
-import json
-import logging
 from praisonaiagents._logging import get_logger
 import os
 from typing import Dict, List, Optional, Set
@@ -91,10 +88,19 @@ class ApprovalRegistry:
        self._global_backend = None  # type: ignore[assignment]
        self._agent_backends: Dict[str, object] = {}

-        # Tool requirements (mirrors old APPROVAL_REQUIRED_TOOLS / TOOL_RISK_LEVELS)
+        # Tool requirements (mirrors old APPROVAL_REQUIRED_TOOLS / TOOL_RISK_LEVELS).
+        # These hold process-wide defaults (e.g. DEFAULT_DANGEROUS_TOOLS and any
+        # intentional global registration).
        self._required_tools: Set[str] = set()
        self._risk_levels: Dict[str, str] = {}

+        # Per-agent tool requirements. A PermissionManager ``ask`` rule belongs
+        # to a single agent, so it must not leak an approval gate onto unrelated
+        # agents sharing the same process. Mirrors the agent-keyed pattern used
+        # by ``_agent_backends`` / ``_agent_tool_auto_approve``.
+        self._agent_required_tools: Dict[str, Set[str]] = {}
+        self._agent_risk_levels: Dict[tuple[str, str], str] = {}
+
        # Per-agent, per-tool auto-approval (G-A fix)
        self._agent_tool_auto_approve: Dict[tuple[str, str], bool] = {}

@@ -153,18 +159,51 @@ class ApprovalRegistry:

    # ── Tool requirement management ──────────────────────────────────────

-    def add_requirement(self, tool_name: str, risk_level: str = "high") -> None:
-        self._required_tools.add(tool_name)
-        self._risk_levels[tool_name] = risk_level
+    def add_requirement(
+        self,
+        tool_name: str,
+        risk_level: str = "high",
+        agent_name: Optional[str] = None,
+    ) -> None:
+        """Mark *tool_name* as requiring approval.

-    def remove_requirement(self, tool_name: str) -> None:
-        self._required_tools.discard(tool_name)
-        self._risk_levels.pop(tool_name, None)
+        When *agent_name* is given the requirement is scoped to that agent only
+        (used for per-agent ``PermissionManager`` ``ask`` rules), so it never
+        forces approval onto other agents in the same process. Omitting
+        *agent_name* keeps the historical process-wide behaviour used for
+        genuinely dangerous tools registered at startup.
+        """
+        if agent_name:
+            self._agent_required_tools.setdefault(agent_name, set()).add(tool_name)
+            self._agent_risk_levels[(agent_name, tool_name)] = risk_level
+        else:
+            self._required_tools.add(tool_name)
+            self._risk_levels[tool_name] = risk_level

-    def is_required(self, tool_name: str) -> bool:
+    def remove_requirement(
+        self, tool_name: str, agent_name: Optional[str] = None
+    ) -> None:
+        if agent_name:
+            tools = self._agent_required_tools.get(agent_name)
+            if tools is not None:
+                tools.discard(tool_name)
+            self._agent_risk_levels.pop((agent_name, tool_name), None)
+        else:
+            self._required_tools.discard(tool_name)
+            self._risk_levels.pop(tool_name, None)
+
+    def is_required(self, tool_name: str, agent_name: Optional[str] = None) -> bool:
+        if agent_name and tool_name in self._agent_required_tools.get(agent_name, ()):
+            return True
        return tool_name in self._required_tools

-    def get_risk_level(self, tool_name: str) -> Optional[str]:
+    def get_risk_level(
+        self, tool_name: str, agent_name: Optional[str] = None
+    ) -> Optional[str]:
+        if agent_name:
+            level = self._agent_risk_levels.get((agent_name, tool_name))
+            if level is not None:
+                return level
        return self._risk_levels.get(tool_name)

    # ── Per-tool auto-approval (G-A fix) ─────────────────────────────────
@@ -184,20 +223,37 @@ class ApprovalRegistry:
    # ── Context helpers ──────────────────────────────────────────────────

    @staticmethod
-    def _approval_cache_key(tool_name: str, arguments: Dict) -> str:
-        payload = json.dumps(arguments or {}, sort_keys=True, default=str)
-        digest = hashlib.sha256(payload.encode()).hexdigest()[:16]
-        return f"{tool_name}:{digest}"
+    def _approval_cache_key(
+        tool_name: str, arguments: Dict, agent_name: Optional[str] = None
+    ) -> str:
+        # Scope the key to the requesting agent so one agent's approval never
+        # silently pre-authorizes an identical call from a different, stricter
+        # agent in the same context. ``*`` is the sentinel for calls made
+        # outside any Agent (e.g. bare module-level tool calls).
+        from .utils import hash_tool_args
+        return f"{agent_name or '*'}:{tool_name}:{hash_tool_args(arguments)}"

-    def mark_approved(self, tool_name: str, arguments: Optional[Dict] = None) -> None:
+    def mark_approved(
+        self,
+        tool_name: str,
+        arguments: Optional[Dict] = None,
+        agent_name: Optional[str] = None,
+    ) -> None:
        approved = self._approved_context.get(set())
-        approved.add(self._approval_cache_key(tool_name, arguments or {}))
+        approved.add(self._approval_cache_key(tool_name, arguments or {}, agent_name))
        self._approved_context.set(approved)

-    def is_already_approved(self, tool_name: str, arguments: Optional[Dict] = None) -> bool:
-        if self.get_risk_level(tool_name) == "critical":
-            return False
-        return self._approval_cache_key(tool_name, arguments or {}) in self._approved_context.get(set())
+    def is_already_approved(
+        self,
+        tool_name: str,
+        arguments: Optional[Dict] = None,
+        agent_name: Optional[str] = None,
+    ) -> bool:
+        # Honour an explicit mark_approved() from the agent approval path even
+        # for critical tools (e.g. execute_command after AutoApproveBackend).
+        if self._approval_cache_key(tool_name, arguments or {}, agent_name) in self._approved_context.get(set()):
+            return True
+        return False

    def _is_session_scoped(
        self, agent_name: Optional[str], tool_name: str, arguments: Optional[Dict]
@@ -344,34 +400,41 @@ class ApprovalRegistry:
        agent_name: Optional[str],
        tool_name: str,
        arguments: Dict,
+        force: bool = False,
    ) -> ApprovalDecision:
-        """Synchronous approval — used by ``Agent._execute_tool_impl``."""
-        # Fast-path: not required
-        if not self.is_required(tool_name):
+        """Synchronous approval — used by ``Agent._execute_tool_impl``.
+
+        ``force`` gates this single call even when the tool is not otherwise
+        registered as requiring approval (e.g. a per-agent ``PermissionManager``
+        ``ask`` rule). It applies only to this call and never mutates shared
+        registry state, so it cannot leak an approval gate onto other agents.
+        """
+        # Fast-path: not required (checks both global and this agent's scope)
+        if not force and not self.is_required(tool_name, agent_name):
            return ApprovalDecision(approved=True, reason="No approval required")

        # Already approved in this context
-        if self.is_already_approved(tool_name, arguments):
+        if self.is_already_approved(tool_name, arguments, agent_name):
            return ApprovalDecision(approved=True, reason="Already approved in context")

        # "This session" scoped grant covers matching calls for the run
        if self._is_session_scoped(agent_name, tool_name, arguments):
-            self.mark_approved(tool_name, arguments)
+            self.mark_approved(tool_name, arguments, agent_name)
            return ApprovalDecision(approved=True, reason="Approved (session)", approver="session")

        # Check per-tool auto-approval (G-A fix)
        if self.is_auto_approved(tool_name, agent_name):
-            self.mark_approved(tool_name, arguments)
+            self.mark_approved(tool_name, arguments, agent_name)
            return ApprovalDecision(approved=True, reason="Auto-approved (skill)", approver="skill")

        # Env auto-approve
        if self.is_env_auto_approve():
-            self.mark_approved(tool_name, arguments)
+            self.mark_approved(tool_name, arguments, agent_name)
            return ApprovalDecision(approved=True, reason="Auto-approved (env)", approver="env")

        # YAML auto-approve
        if self.is_yaml_approved(tool_name):
-            self.mark_approved(tool_name, arguments)
+            self.mark_approved(tool_name, arguments, agent_name)
            return ApprovalDecision(approved=True, reason="Auto-approved (yaml)", approver="yaml")

        # Delegate to backend
@@ -379,7 +442,7 @@ class ApprovalRegistry:
        request = ApprovalRequest(
            tool_name=tool_name,
            arguments=arguments,
-            risk_level=self._risk_levels.get(tool_name, "medium"),
+            risk_level=self.get_risk_level(tool_name, agent_name) or "medium",
            agent_name=agent_name,
        )

@@ -395,7 +458,7 @@ class ApprovalRegistry:
            )

        if decision.approved:
-            self.mark_approved(tool_name, arguments)
+            self.mark_approved(tool_name, arguments, agent_name)
        self._persist_scoped_decision(agent_name, tool_name, arguments, decision)
        return decision

@@ -404,38 +467,43 @@ class ApprovalRegistry:
        agent_name: Optional[str],
        tool_name: str,
        arguments: Dict,
+        force: bool = False,
    ) -> ApprovalDecision:
-        """Asynchronous approval — used by async tool execution path."""
-        # Fast-path: not required
-        if not self.is_required(tool_name):
+        """Asynchronous approval — used by async tool execution path.
+
+        See :meth:`approve_sync` for the ``force`` semantics (per-call gate,
+        no shared-state mutation).
+        """
+        # Fast-path: not required (checks both global and this agent's scope)
+        if not force and not self.is_required(tool_name, agent_name):
            return ApprovalDecision(approved=True, reason="No approval required")

-        if self.is_already_approved(tool_name, arguments):
+        if self.is_already_approved(tool_name, arguments, agent_name):
            return ApprovalDecision(approved=True, reason="Already approved in context")

        # "This session" scoped grant covers matching calls for the run
        if self._is_session_scoped(agent_name, tool_name, arguments):
-            self.mark_approved(tool_name, arguments)
+            self.mark_approved(tool_name, arguments, agent_name)
            return ApprovalDecision(approved=True, reason="Approved (session)", approver="session")

        # Check per-tool auto-approval (G-A fix)
        if self.is_auto_approved(tool_name, agent_name):
-            self.mark_approved(tool_name, arguments)
+            self.mark_approved(tool_name, arguments, agent_name)
            return ApprovalDecision(approved=True, reason="Auto-approved (skill)", approver="skill")

        if self.is_env_auto_approve():
-            self.mark_approved(tool_name, arguments)
+            self.mark_approved(tool_name, arguments, agent_name)
            return ApprovalDecision(approved=True, reason="Auto-approved (env)", approver="env")

        if self.is_yaml_approved(tool_name):
-            self.mark_approved(tool_name, arguments)
+            self.mark_approved(tool_name, arguments, agent_name)
            return ApprovalDecision(approved=True, reason="Auto-approved (yaml)", approver="yaml")

        backend = self.get_backend(agent_name)
        request = ApprovalRequest(
            tool_name=tool_name,
            arguments=arguments,
-            risk_level=self._risk_levels.get(tool_name, "medium"),
+            risk_level=self.get_risk_level(tool_name, agent_name) or "medium",
            agent_name=agent_name,
        )

@@ -448,6 +516,6 @@ class ApprovalRegistry:
            decision = ApprovalDecision(approved=False, reason="Approval timed out")

        if decision.approved:
-            self.mark_approved(tool_name, arguments)
+            self.mark_approved(tool_name, arguments, agent_name)
        self._persist_scoped_decision(agent_name, tool_name, arguments, decision)
        return decision
@@ -7,11 +7,31 @@ across the approval system.

 import asyncio
 import concurrent.futures
+import hashlib
+import json
 from typing import Any, Awaitable, Callable, Dict, Optional, TypeVar

 T = TypeVar('T')


+def hash_tool_args(arguments: Optional[Dict[str, Any]]) -> str:
+    """Return the canonical 16-char identity hash of a tool call's arguments.
+
+    Produces a 16-character SHA-256 digest over the canonical JSON encoding
+    (``sort_keys=True, default=str``) of the arguments. This is the single
+    source of truth for the tool-call identity key shared by approval
+    de-duplication (``ApprovalRegistry``) and doom-loop detection, so the two
+    safety subsystems cannot silently diverge.
+
+    Falls back to ``"unhashable"`` if the arguments cannot be serialised.
+    """
+    try:
+        payload = json.dumps(arguments or {}, sort_keys=True, default=str)
+        return hashlib.sha256(payload.encode()).hexdigest()[:16]
+    except (TypeError, ValueError):
+        return "unhashable"
+
+
 # Tool names that map to a shell-command permission target (``bash:<command>``)
 # so the reusable command-prefix machinery in ``PermissionManager`` applies.
 _SHELL_TOOLS = frozenset({
@@ -56,6 +76,14 @@ def build_permission_target(
    * file tools  -> ``<edit|write|delete|…>:<path>``
    * everything else -> ``tool:<tool_name>``

+    The command identity is preserved verbatim so command-specific rules
+    (e.g. ``deny: bash:rm *``) still match. The out-of-workspace boundary is
+    enforced downstream by :class:`~praisonaiagents.permissions.PermissionManager`
+    (its ``external_dir:`` gate), which decomposes the ``bash:<command>`` target
+    and gates any escaping path — so a broad ``bash:*`` / "allow shell" /
+    session grant cannot silently authorise out-of-workspace access while a
+    command-specific ``deny`` still fires.
+
    Falls back to ``tool:<tool_name>`` whenever the expected argument is missing
    so a target is always produced.

@@ -40,6 +40,8 @@ __all__ = [
    "TaskStatus",
    # Configuration
    "BackgroundConfig",
+    # Shared runner accessor
+    "get_background_runner",
 ]


@@ -61,4 +63,8 @@ def __getattr__(name: str):
        from .config import BackgroundConfig
        return BackgroundConfig
    
+    if name == "get_background_runner":
+        from .runner import get_background_runner
+        return get_background_runner
+    
    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
@@ -5,7 +5,6 @@ Manages background task execution.
 """

 import asyncio
-import logging
 import threading
 from praisonaiagents._logging import get_logger
 from typing import Optional, List, Dict, Any, Callable, Union
@@ -363,6 +362,24 @@ class BackgroundRunner:
        # Block briefly to get the BackgroundTask object (not the task result).
        return future.result(timeout=5)

+    def cancel_task_sync(self, task_id: str) -> bool:
+        """Cancel a task from synchronous code (or an unrelated event loop).
+
+        Schedules :meth:`cancel_task` on the shared background loop where the
+        task's future lives, so the underlying execution is actually stopped
+        (not merely marked cancelled). Safe to call from within a running
+        event loop because it hops threads via ``run_coroutine_threadsafe``.
+
+        Args:
+            task_id: ID of task to cancel
+
+        Returns:
+            True if cancelled, False if not found or already completed
+        """
+        loop = _get_bg_loop()
+        future = asyncio.run_coroutine_threadsafe(self.cancel_task(task_id), loop)
+        return future.result(timeout=5)
+
    def submit_agent_sync(
        self,
        agent: Any,
@@ -452,3 +469,25 @@ def _shutdown_bg_loop():
 # Register cleanup on process exit
 import atexit
 atexit.register(_shutdown_bg_loop)
+
+
+# ── Shared process-wide runner ──────────────────────────────────────────
+
+_shared_runner: Optional["BackgroundRunner"] = None
+_shared_runner_lock = _threading.Lock()
+
+
+def get_background_runner() -> "BackgroundRunner":
+    """Return the process-wide shared :class:`BackgroundRunner`.
+
+    Interactive surfaces (REPL/TUI) and bots submit and inspect background
+    tasks through this single instance so ``/tasks`` sees the same tasks
+    regardless of which surface submitted them. Created lazily on first use.
+    """
+    global _shared_runner
+    if _shared_runner is not None:
+        return _shared_runner
+    with _shared_runner_lock:
+        if _shared_runner is None:
+            _shared_runner = BackgroundRunner()
+    return _shared_runner
@@ -6,7 +6,6 @@ Represents a task running in the background.

 import uuid
 import asyncio
-import logging
 from praisonaiagents._logging import get_logger
 from enum import Enum
 from dataclasses import dataclass, field
@@ -27,12 +27,16 @@ from .protocols import (
    EmailProtocol,
    EmailInbox,
    SupportsPresentation,
+    PresentationRendererProtocol,
    PlatformCapabilities,
    ChannelField,
    ChannelDescriptor,
    WebhookVerifierProtocol,
    CallbackPayloadStoreProtocol,
    InMemoryCallbackPayloadStore,
+    GatewayRuntimeSeams,
+    SupportsGatewayRuntime,
+    GatewayAdapterContractError,
 )
 from .base import (
    BasePlatformAdapter,
@@ -49,6 +53,12 @@ from .presentation import (
    ButtonStyle,
    BlockType,
    adapt_presentation,
+    adapt_presentation_with_report,
+    DegradedDelivery,
+    table_to_markdown,
+    chart_to_text,
+    register_presentation_renderer,
+    get_presentation_renderer,
 )
 from .interactive import (
    InteractiveContext,
@@ -71,13 +81,33 @@ from .agent_reply import (
    extract_completion,
    append_completion_note,
 )
+from .format import (
+    format_for_dialect,
+    escape_markdown_v2,
+    markdown_to_slack,
+    strip_markdown,
+)
+from .webhook_filter import (
+    WebhookFilter,
+    evaluate_webhook_filter,
+    resolve_field,
+)
 from .config import BotConfig, BotOSConfig, DisplayPolicy, resolve_display_policy
 from .silence import (
    SILENT_REPLY_TOKEN,
    is_intentional_silence_response,
+    classify_final,
    BotLoopPolicy,
    BotLoopGuard,
 )
+from .failure import (
+    FailureReply,
+    render_failure_reply,
+)
+from .admission import (
+    IngressDecision,
+    resolve_ingress_admission,
+)
 from .run_status import (
    RunPhase,
    RunStatusController,
@@ -116,12 +146,25 @@ __all__ = [
    "ButtonStyle",
    "BlockType",
    "adapt_presentation",
+    "adapt_presentation_with_report",
+    "DegradedDelivery",
+    "table_to_markdown",
+    "chart_to_text",
+    "PresentationRendererProtocol",
+    "register_presentation_renderer",
+    "get_presentation_renderer",
    "PlatformCapabilities",
    "ChannelField",
    "ChannelDescriptor",
    "WebhookVerifierProtocol",
+    "WebhookFilter",
+    "evaluate_webhook_filter",
+    "resolve_field",
    "CallbackPayloadStoreProtocol",
    "InMemoryCallbackPayloadStore",
+    "GatewayRuntimeSeams",
+    "SupportsGatewayRuntime",
+    "GatewayAdapterContractError",
    "BasePlatformAdapter",
    "SendResult",
    "InteractiveContext",
@@ -141,10 +184,19 @@ __all__ = [
    "extract_presentation",
    "extract_completion",
    "append_completion_note",
+    "format_for_dialect",
+    "escape_markdown_v2",
+    "markdown_to_slack",
+    "strip_markdown",
    "SILENT_REPLY_TOKEN",
    "is_intentional_silence_response",
+    "classify_final",
    "BotLoopPolicy",
    "BotLoopGuard",
+    "FailureReply",
+    "render_failure_reply",
+    "IngressDecision",
+    "resolve_ingress_admission",
    "RunPhase",
    "RunStatusController",
    "StallState",
@@ -0,0 +1,220 @@
+"""
+Inbound admission primitive for bot gateways.
+
+Provides a single, pure, dependency-free decision for "should the bot act on
+this inbound message?" — channel/user allowlist, block-list, group policy
+(``respond_all`` / ``mention_only`` / ``command_only`` / ``observe``) and
+pairing for unknown users — returning a typed verdict with a machine-readable
+reason code an operator can inspect.
+
+Like :func:`praisonaiagents.bots.protocols.evaluate_channel_health` and
+:class:`praisonaiagents.bots.silence.BotLoopGuard`, this is a zero-dependency
+decision primitive: every channel adapter (built-in or plugin) feeds it native
+message facts and acts on the verdict, so the admission decision cannot drift
+across transports and a drop is no longer a silent ``logger.debug`` line but a
+recorded ``reason_code``.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Iterable, Optional
+
+# Machine-readable reason codes. Kept as module constants so callers can record
+# and compare them without re-typing string literals (which is exactly how the
+# per-channel logic drifted).
+REASON_ALLOWED = "allowed"
+REASON_NOT_IN_ALLOWLIST = "not_in_allowlist"
+REASON_BLOCKED = "blocked"
+REASON_GROUP_MENTION_ONLY = "group_mention_only"
+REASON_OBSERVE = "observe"
+REASON_PAIRING_REQUIRED = "pairing_required"
+REASON_COMMAND_ONLY = "command_only"
+
+# Gate names — which stage of the ladder produced the verdict.
+GATE_BLOCKLIST = "blocklist"
+GATE_ALLOWLIST = "allowlist"
+GATE_PAIRING = "pairing"
+GATE_GROUP_POLICY = "group_policy"
+GATE_DIRECT = "direct"
+
+# Group policies, matching the existing YAML ``group_policy`` values.
+_GROUP_POLICIES = frozenset(
+    {"respond_all", "mention_only", "command_only", "observe"}
+)
+
+# Chat types treated as one-to-one (no group policy applies).
+_DIRECT_CHAT_TYPES = frozenset({"dm", "private", "direct", "im"})
+
+
+@dataclass(frozen=True)
+class IngressDecision:
+    """Typed verdict for an inbound admission decision.
+
+    Attributes:
+        admit: Whether the bot should run the agent on this message. ``False``
+            means the message is dropped (or only passively observed).
+        reason_code: A machine-readable reason (one of the ``REASON_*``
+            constants) an operator can inspect to answer "why didn't the bot
+            reply to that message?".
+        gate: Which gate decided (one of the ``GATE_*`` constants), for
+            diagnostics.
+        observe: When ``True`` the message was not admitted for a run but SHOULD
+            be recorded into the session transcript as passive context (the
+            ``observe`` group policy). Adapters record it and skip the run.
+    """
+
+    admit: bool
+    reason_code: str
+    gate: str
+    observe: bool = False
+
+
+def _contains(collection: Optional[Iterable[str]], value: Optional[str]) -> bool:
+    """Membership test tolerant of ``None`` collection/value.
+
+    An empty or ``None`` collection means "no restriction configured" and is
+    handled by the caller — this only answers whether ``value`` is present.
+    """
+    if not collection or value is None:
+        return False
+    return value in collection
+
+
+def resolve_ingress_admission(
+    *,
+    chat_type: Optional[str],
+    sender_id: Optional[str],
+    is_mention: bool = False,
+    is_command: bool = False,
+    allowlist: Optional[Iterable[str]] = None,
+    blocklist: Optional[Iterable[str]] = None,
+    group_policy: Optional[str] = None,
+    paired: bool = True,
+) -> IngressDecision:
+    """Decide whether the bot should act on an inbound message.
+
+    Pure, deterministic and zero-dependency: the same inputs always yield the
+    same verdict, so the decision cannot drift across transports or plugin
+    channels. Every adapter replaces its bespoke ladder with one call and
+    records ``decision.reason_code``.
+
+    The ladder (first matching gate wins):
+
+    1. **Block-list** — an explicitly blocked sender is always dropped
+       (``blocked``), taking precedence over any allowlist entry.
+    2. **Allow-list** — when an ``allowlist`` is configured and the sender is
+       not in it, drop (``not_in_allowlist``). An empty/``None`` allowlist means
+       "no allowlist restriction".
+    3. **Pairing** — an unknown but not-yet-``paired`` sender that passed the
+       allowlist gate requires pairing (``pairing_required``).
+    4. **Group policy** — for group/channel chats only:
+         - ``command_only``: admit commands, else drop (``command_only``);
+         - ``mention_only``: admit mentions/commands, else drop
+           (``group_mention_only``);
+         - ``observe``: admit mentions/commands, else *observe* (recorded, no
+           run) with reason ``observe``;
+         - ``respond_all``: admit everything;
+         - unset/unknown: treated as ``mention_only`` (the live
+           ``BotConfig.group_policy`` default), so an adapter forwarding an
+           unset policy does not silently reply to all group traffic.
+
+    Direct (DM/private) chats skip the group-policy gate entirely.
+
+    Args:
+        chat_type: Native chat type (e.g. ``"dm"``, ``"private"``, ``"group"``,
+            ``"channel"``, ``"supergroup"``). Anything not in the direct set is
+            treated as a group for policy purposes.
+        sender_id: Stable sender identifier used for allow/block-list checks.
+        is_mention: Whether the bot was mentioned/@-addressed in the message.
+        is_command: Whether the message is a bot command (always allowed under
+            ``mention_only`` / ``command_only`` / ``observe``).
+        allowlist: Optional collection of allowed sender ids to *enforce*.
+            Empty/``None`` disables the allowlist gate (no restriction). This is
+            the already-resolved list — an adapter that wants an empty allowlist
+            to mean "deny unknown" (``BotConfig.is_explicitly_allowed`` +
+            ``unknown_user_policy``) resolves that upstream into the ``paired``
+            flag rather than passing an empty ``allowlist`` here.
+        blocklist: Optional collection of blocked sender ids.
+        group_policy: One of ``respond_all`` / ``mention_only`` /
+            ``command_only`` / ``observe``. ``None`` or unknown values behave as
+            ``mention_only`` — the live ``BotConfig.group_policy`` default — so
+            an unset policy fails safe (mention-gated) rather than open.
+        paired: Whether the sender is already paired/known. ``True`` (the
+            default) means pairing is not required.
+
+    Returns:
+        An :class:`IngressDecision` with the verdict, a machine-readable
+        ``reason_code``, the deciding ``gate`` and the ``observe`` flag.
+    """
+    # 1. Block-list wins over everything: an explicitly blocked sender never
+    #    reaches an agent run regardless of allowlist membership.
+    if _contains(blocklist, sender_id):
+        return IngressDecision(
+            admit=False, reason_code=REASON_BLOCKED, gate=GATE_BLOCKLIST
+        )
+
+    # 2. Allow-list: only enforced when configured. Absent/empty => no restriction.
+    if allowlist and not _contains(allowlist, sender_id):
+        return IngressDecision(
+            admit=False,
+            reason_code=REASON_NOT_IN_ALLOWLIST,
+            gate=GATE_ALLOWLIST,
+        )
+
+    # 3. Pairing: an allowed-but-unknown sender must complete pairing first.
+    if not paired:
+        return IngressDecision(
+            admit=False,
+            reason_code=REASON_PAIRING_REQUIRED,
+            gate=GATE_PAIRING,
+        )
+
+    # Direct chats bypass group policy entirely.
+    is_direct = (chat_type or "").lower() in _DIRECT_CHAT_TYPES
+    if is_direct:
+        return IngressDecision(
+            admit=True, reason_code=REASON_ALLOWED, gate=GATE_DIRECT
+        )
+
+    # 4. Group policy for group/channel chats. Unknown/None => mention_only,
+    #    matching the live ``BotConfig.group_policy`` default so an adapter that
+    #    forwards an unset policy does not silently start replying to all group
+    #    traffic (a security-relevant regression).
+    policy = (group_policy or "mention_only").lower()
+
+    if policy == "command_only":
+        if is_command:
+            return IngressDecision(
+                admit=True, reason_code=REASON_ALLOWED, gate=GATE_GROUP_POLICY
+            )
+        return IngressDecision(
+            admit=False,
+            reason_code=REASON_COMMAND_ONLY,
+            gate=GATE_GROUP_POLICY,
+        )
+
+    if policy in ("mention_only", "observe"):
+        if is_mention or is_command:
+            return IngressDecision(
+                admit=True, reason_code=REASON_ALLOWED, gate=GATE_GROUP_POLICY
+            )
+        if policy == "observe":
+            # Recorded as passive context (no run) so the bot has memory of the
+            # conversation when next addressed.
+            return IngressDecision(
+                admit=False,
+                reason_code=REASON_OBSERVE,
+                gate=GATE_GROUP_POLICY,
+                observe=True,
+            )
+        return IngressDecision(
+            admit=False,
+            reason_code=REASON_GROUP_MENTION_ONLY,
+            gate=GATE_GROUP_POLICY,
+        )
+
+    # respond_all (or any unknown policy): admit everything.
+    return IngressDecision(
+        admit=True, reason_code=REASON_ALLOWED, gate=GATE_GROUP_POLICY
+    )
@@ -278,8 +278,26 @@ class BasePlatformAdapter(ABC):
    # ------------------------------------------------------------------ #

    def format_message(self, text: str) -> str:
-        """Apply per-platform formatting. Default: identity."""
-        return text
+        """Render *text* for the platform's declared ``markdown_dialect``.
+
+        This is the seam that finally *consumes* the ``markdown_dialect``
+        capability every adapter advertises: the default keys off
+        ``capabilities.markdown_dialect`` and returns text rendered in that
+        flavour (e.g. MarkdownV2-escaped for Telegram, Slack ``mrkdwn`` for
+        Slack) so replies render correctly and are never dropped by a transport
+        that rejects unescaped specials. The default dialect ``"markdown"``
+        yields a safe plain-text reduction, so existing adapters are unaffected.
+
+        Adapters that need the transport ``parse_mode`` (e.g. Telegram's
+        ``"MarkdownV2"``) can call :func:`~praisonaiagents.bots.format_for_dialect`
+        directly in their send path; override this method to change formatting.
+        """
+        from .format import format_for_dialect
+
+        rendered, _parse_mode = format_for_dialect(
+            text, self._cap("markdown_dialect", "markdown")
+        )
+        return rendered

    def chunk(self, text: str) -> List[str]:
        """Split *text* to respect the platform max length.
@@ -51,7 +51,7 @@ class BotConfig:
    thread_threshold: int = 500  # Auto-thread responses longer than this (0 = disabled)
    
    # Group message policy
-    group_policy: str = "mention_only"  # respond_all, mention_only, command_only
+    group_policy: str = "mention_only"  # respond_all, mention_only, command_only, observe
    
    # Default safe tools (auto-injected for bots with no tools configured)
    # With workspace scoping, file operations are now safe by construction
@@ -0,0 +1,286 @@
+"""
+Visible failure-outcome primitive for bot gateways.
+
+:func:`classify_final` (``bots/silence.py``) guarantees a visible outcome for a
+*blank* turn, but says nothing about a turn that **failed** (expired auth,
+missing key, rate limit, timeout, budget/doom-loop) — where the user today sees
+a generic ``Error: <msg>`` or a silent downgrade. A rich error taxonomy already
+exists in :mod:`praisonaiagents.errors` and :mod:`praisonaiagents.run_outcome`,
+but nothing maps it to a *user-facing, actionable* reply, so every channel
+adapter re-decides it ad hoc (the drift this closes).
+
+This module is the failure-path counterpart of ``classify_final`` /
+``resolve_ingress_admission``: a single, pure, dependency-free decision that maps
+an :class:`~praisonaiagents.run_outcome.AgentRunOutcome` or a
+:class:`~praisonaiagents.errors.PraisonAIError` to a typed :class:`FailureReply`
+with next-step copy keyed by failure class, reusing the existing
+``remediation_hint``. Every adapter renders ``reply.text`` and records
+``reply.reason_code`` instead of hand-rolling ``Error: …`` strings.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any, Optional
+
+if TYPE_CHECKING:  # pragma: no cover - typing only, avoids import cost/cycles
+    from ..errors import PraisonAIError
+    from ..run_outcome import AgentRunOutcome
+
+
+# Machine-readable failure reason codes. Module constants (like the ``REASON_*``
+# codes in ``admission.py``) so callers record/compare without re-typing string
+# literals — exactly the drift that produced the per-adapter ``Error: …`` copy.
+REASON_AUTH_EXPIRED = "auth_expired"
+REASON_AUTH_PERMANENT = "auth_permanent"
+REASON_MISSING_KEY = "missing_key"
+REASON_RATE_LIMIT = "rate_limit"
+REASON_OVERLOADED = "overloaded"
+REASON_TIMEOUT = "timeout"
+REASON_BUDGET_EXHAUSTED = "budget_exhausted"
+REASON_DOOM_LOOP = "doom_loop"
+REASON_NEEDS_HELP = "needs_help"
+REASON_CANCELLED = "cancelled"
+REASON_CONTEXT_OVERFLOW = "context_overflow"
+REASON_MODEL_NOT_FOUND = "model_not_found"
+REASON_FORMAT_ERROR = "format_error"
+REASON_UNKNOWN = "unknown"
+
+
+# Static, user-facing next-step copy keyed by failure class. Kept deterministic
+# and channel-agnostic so the same guidance appears on every transport. A
+# concrete ``remediation_hint`` (e.g. from ``PraisonAIConfigError``) always wins
+# over these defaults when present.
+_REASON_TEXT = {
+    REASON_AUTH_EXPIRED: (
+        "I couldn't complete that - the model credential has expired. "
+        "Run `praisonai onboard` to re-authenticate, then resend."
+    ),
+    REASON_AUTH_PERMANENT: (
+        "I couldn't complete that - the model credential was rejected. "
+        "Check the API key/permissions, then run `praisonai onboard` and resend."
+    ),
+    REASON_MISSING_KEY: (
+        "I couldn't complete that - a required credential is missing. "
+        "Run `praisonai onboard` (or `praisonai doctor`) to set it up, then resend."
+    ),
+    REASON_RATE_LIMIT: (
+        "I couldn't complete that - the provider is rate-limiting requests. "
+        "Please wait a moment and resend."
+    ),
+    REASON_OVERLOADED: (
+        "I couldn't complete that - the provider is temporarily overloaded. "
+        "Please wait a moment and resend."
+    ),
+    REASON_TIMEOUT: (
+        "I couldn't complete that in time - the request timed out. "
+        "Please resend, or try a shorter request."
+    ),
+    REASON_BUDGET_EXHAUSTED: (
+        "I stopped before finishing - this turn hit its budget limit. "
+        "Raise the budget or narrow the task, then resend."
+    ),
+    REASON_DOOM_LOOP: (
+        "I stopped before finishing - I detected a repeating loop and halted to "
+        "avoid wasting effort. Try rephrasing the request, then resend."
+    ),
+    REASON_NEEDS_HELP: (
+        "I need a bit more to continue - please clarify or provide the missing "
+        "detail, then resend."
+    ),
+    REASON_CANCELLED: "That request was cancelled before it finished.",
+    REASON_CONTEXT_OVERFLOW: (
+        "I couldn't complete that - the conversation is too long for the model. "
+        "Start a fresh thread or shorten the request, then resend."
+    ),
+    REASON_MODEL_NOT_FOUND: (
+        "I couldn't complete that - the configured model is unavailable. "
+        "Check the model name in your config, then resend."
+    ),
+    REASON_FORMAT_ERROR: (
+        "I couldn't complete that - the request or configuration was invalid. "
+        "Please check the input and resend."
+    ),
+    REASON_UNKNOWN: "I couldn't complete that due to an unexpected error. Please resend.",
+}
+
+# Which failure classes are worth retrying without user intervention. Mirrors the
+# taxonomy in ``errors.AgentErrorKind`` / ``AgentRunOutcome.is_retryable`` so the
+# adapter can decide whether to offer a "retry" affordance.
+_RETRYABLE_REASONS = frozenset(
+    {REASON_RATE_LIMIT, REASON_OVERLOADED, REASON_TIMEOUT}
+)
+
+# Map the closed ``AgentErrorKind`` taxonomy to a user-facing reason code. Auth
+# is split into expired vs permanent so re-authentication guidance is precise.
+_ERROR_KIND_TO_REASON = {
+    "auth": REASON_AUTH_EXPIRED,
+    "auth_permanent": REASON_AUTH_PERMANENT,
+    "rate_limit": REASON_RATE_LIMIT,
+    "overloaded": REASON_OVERLOADED,
+    "context_overflow": REASON_CONTEXT_OVERFLOW,
+    "idle_timeout": REASON_TIMEOUT,
+    "billing": REASON_BUDGET_EXHAUSTED,
+    "model_not_found": REASON_MODEL_NOT_FOUND,
+    "format_error": REASON_FORMAT_ERROR,
+    "validation": REASON_FORMAT_ERROR,
+    "unknown": REASON_UNKNOWN,
+}
+
+# Map an ``AgentRunOutcome`` termination context / status to a reason code.
+_TERMINATION_TO_REASON = {
+    "budget_exhausted": REASON_BUDGET_EXHAUSTED,
+    "doom_loop": REASON_DOOM_LOOP,
+    "needs_help": REASON_NEEDS_HELP,
+    "timeout": REASON_TIMEOUT,
+    "cancelled": REASON_CANCELLED,
+    "interrupted": REASON_CANCELLED,
+}
+
+
+@dataclass(frozen=True)
+class FailureReply:
+    """A typed, user-facing reply for a failed turn.
+
+    Attributes:
+        text: The visible, actionable message to deliver to the user. Includes
+            next-step copy keyed by the failure class (how to re-authenticate,
+            run onboarding, wait out a rate limit, etc.).
+        reason_code: A machine-readable failure class (one of the ``REASON_*``
+            constants) an operator/model can inspect and record.
+        retryable: Whether the failure is worth retrying without user
+            intervention (rate limit, overload, transient timeout).
+    """
+
+    text: str
+    reason_code: str
+    retryable: bool
+
+
+def _reason_from_error(error: "PraisonAIError") -> str:
+    """Derive a reason code from a :class:`PraisonAIError`.
+
+    A missing/blank config key surfaces as ``missing_key`` (distinct from an
+    expired credential) so the onboarding vs re-auth guidance stays precise.
+    """
+    category = getattr(error, "error_category", None) or "unknown"
+    # A config error carrying a config_key is a *missing* credential/setting,
+    # not a rejected one — steer the user to onboarding rather than re-auth.
+    if getattr(error, "config_key", None) and category == "format_error":
+        return REASON_MISSING_KEY
+    return _ERROR_KIND_TO_REASON.get(category, REASON_UNKNOWN)
+
+
+def _reason_from_outcome(outcome: "AgentRunOutcome") -> str:
+    """Derive a reason code from an :class:`AgentRunOutcome`.
+
+    Prefers a specific ``termination_reason`` recorded in the outcome context
+    (budget/doom-loop/needs-help) before falling back to the error category and
+    finally the coarse status.
+    """
+    context = getattr(outcome, "context", None) or {}
+    termination = context.get("termination_reason") or context.get("termination")
+    if termination is not None:
+        key = getattr(termination, "value", termination)
+        mapped = _TERMINATION_TO_REASON.get(str(key))
+        if mapped is not None:
+            return mapped
+
+    category = getattr(outcome, "error_category", None)
+    if category:
+        mapped = _ERROR_KIND_TO_REASON.get(category)
+        if mapped is not None:
+            return mapped
+
+    status = getattr(outcome, "status", None)
+    if status == "timeout":
+        return REASON_TIMEOUT
+    if status == "cancelled":
+        return REASON_CANCELLED
+    if status == "invalid_output":
+        return REASON_FORMAT_ERROR
+    return REASON_UNKNOWN
+
+
+def render_failure_reply(outcome: Any) -> FailureReply:
+    """Map a run outcome or error to a visible, actionable :class:`FailureReply`.
+
+    This is the failure-path counterpart of
+    :func:`praisonaiagents.bots.silence.classify_final`: a single decision point
+    so no adapter re-decides how a failure looks. It accepts either an
+    :class:`~praisonaiagents.run_outcome.AgentRunOutcome` or a
+    :class:`~praisonaiagents.errors.PraisonAIError` (duck-typed to avoid an
+    import dependency), reuses the existing ``remediation_hint`` when present,
+    and otherwise selects deterministic next-step copy keyed by the failure
+    class.
+
+    Args:
+        outcome: An ``AgentRunOutcome``, a ``PraisonAIError`` (or subclass), or
+            any object exposing ``error_category`` / ``status``. A plain string
+            or unknown object degrades to a generic (but still visible)
+            ``unknown`` reply rather than raising.
+
+    Returns:
+        A :class:`FailureReply` with actionable ``text``, a machine-readable
+        ``reason_code`` and a ``retryable`` flag.
+    """
+    # Duck-type the two supported inputs without importing them (keeps this a
+    # zero-dependency leaf like the other bot primitives).
+    is_error = isinstance(outcome, BaseException)
+
+    # Preserve an affirmative retryability signal from the source outcome (e.g.
+    # AgentRunOutcome.is_retryable() is True for invalid_output) so a
+    # reason-code that is not in the static ``_RETRYABLE_REASONS`` default does
+    # not silently drop the retry affordance the outcome already promised.
+    source_retryable = False
+
+    if is_error:
+        reason = _reason_from_error(outcome)  # type: ignore[arg-type]
+        remediation = getattr(outcome, "remediation_hint", None)
+    elif hasattr(outcome, "status") or hasattr(outcome, "error_category"):
+        reason = _reason_from_outcome(outcome)
+        context = getattr(outcome, "context", None) or {}
+        remediation = context.get("remediation_hint")
+        is_retryable = getattr(outcome, "is_retryable", None)
+        if callable(is_retryable):
+            try:
+                source_retryable = bool(is_retryable())
+            except Exception:
+                source_retryable = False
+    else:
+        reason = REASON_UNKNOWN
+        remediation = None
+
+    text: Optional[str] = None
+    if isinstance(remediation, str) and remediation.strip():
+        # A concrete remediation hint (e.g. from PraisonAIConfigError) is the
+        # most precise guidance available — prefer it over the static default.
+        text = f"I couldn't complete that. {remediation.strip()}"
+    if text is None:
+        text = _REASON_TEXT.get(reason, _REASON_TEXT[REASON_UNKNOWN])
+
+    return FailureReply(
+        text=text,
+        reason_code=reason,
+        retryable=source_retryable or reason in _RETRYABLE_REASONS,
+    )
+
+
+__all__ = [
+    "FailureReply",
+    "render_failure_reply",
+    "REASON_AUTH_EXPIRED",
+    "REASON_AUTH_PERMANENT",
+    "REASON_MISSING_KEY",
+    "REASON_RATE_LIMIT",
+    "REASON_OVERLOADED",
+    "REASON_TIMEOUT",
+    "REASON_BUDGET_EXHAUSTED",
+    "REASON_DOOM_LOOP",
+    "REASON_NEEDS_HELP",
+    "REASON_CANCELLED",
+    "REASON_CONTEXT_OVERFLOW",
+    "REASON_MODEL_NOT_FOUND",
+    "REASON_FORMAT_ERROR",
+    "REASON_UNKNOWN",
+]
@@ -0,0 +1,137 @@
+"""
+Markdown dialect conversion for agent replies.
+
+A pure, dependency-free (stdlib-only) default that finally *consumes* the
+``markdown_dialect`` capability every platform adapter already declares
+(:class:`~praisonaiagents.bots.protocols.PlatformCapabilities`). It turns an
+agent's ordinary markdown reply into the flavour the target platform speaks so
+formatting renders correctly and a reply is never dropped by a transport that
+rejects unescaped special characters (e.g. Telegram's ``400 can't parse
+entities``).
+
+The single entry point is :func:`format_for_dialect`, which returns the
+``(rendered_text, parse_mode)`` pair a send path needs::
+
+    text, mode = format_for_dialect(agent_text, caps.markdown_dialect)
+    await bot.send_message(chat_id, text, parse_mode=mode)
+
+Supported dialects:
+
+* ``"telegram_markdown_v2"`` -> MarkdownV2-escaped text, ``parse_mode="MarkdownV2"``
+* ``"slack"``                -> Slack mrkdwn text,        ``parse_mode=None``
+* ``"discord_markdown"``     -> passthrough (Discord speaks CommonMark),
+  ``parse_mode=None``
+* ``"markdown"``/unknown     -> safe plain text,          ``parse_mode=None``
+
+This lives in core because it is the light default for a core protocol seam:
+pure string work, no heavy imports, and driven by the capability contract each
+adapter already advertises. Adapters call it from their send paths.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Optional, Tuple
+
+__all__ = [
+    "format_for_dialect",
+    "escape_markdown_v2",
+    "markdown_to_slack",
+    "strip_markdown",
+]
+
+# Characters Telegram MarkdownV2 requires escaping outside entities.
+# See https://core.telegram.org/bots/api#markdownv2-style
+_MDV2_SPECIAL = r"_*[]()~`>#+-=|{}.!\\"
+_MDV2_ESCAPE_RE = re.compile("([" + re.escape(_MDV2_SPECIAL) + "])")
+
+
+def escape_markdown_v2(text: str) -> str:
+    """Escape every Telegram MarkdownV2 special character in ``text``.
+
+    This is the conservative, always-safe escape: it treats the input as plain
+    text and backslash-escapes each reserved character so Telegram accepts the
+    message verbatim without a ``can't parse entities`` error. Existing markup
+    (``**bold**``, ``[links](url)``) is shown literally rather than reinterpreted;
+    correctness (never dropping a reply) is preferred over best-effort styling.
+    """
+    if not text:
+        return ""
+    return _MDV2_ESCAPE_RE.sub(r"\\\1", text)
+
+
+# Inline markdown -> Slack mrkdwn conversions (order matters: bold before italic).
+_MD_BOLD_RE = re.compile(r"\*\*(.+?)\*\*", re.DOTALL)
+_MD_LINK_RE = re.compile(r"\[([^\]]+)\]\((https?://[^\s)]+)\)")
+_MD_HEADING_RE = re.compile(r"^\s{0,3}#{1,6}\s+(.*)$", re.MULTILINE)
+
+
+def markdown_to_slack(text: str) -> str:
+    """Convert common markdown to Slack ``mrkdwn``.
+
+    Slack uses ``*bold*`` (single asterisk), ``_italic_``, ``<url|label>`` links
+    and has no ``#`` headings. This maps the frequent cases and otherwise leaves
+    text untouched, so a plain reply passes through unchanged.
+    """
+    if not text:
+        return ""
+    # Links: [label](url) -> <url|label>
+    text = _MD_LINK_RE.sub(lambda m: f"<{m.group(2)}|{m.group(1)}>", text)
+    # Bold: **x** -> *x* (do before single-asterisk handling is unnecessary here)
+    text = _MD_BOLD_RE.sub(lambda m: f"*{m.group(1)}*", text)
+    # Headings: "# Title" -> "*Title*" (Slack has no headings)
+    text = _MD_HEADING_RE.sub(lambda m: f"*{m.group(1).strip()}*", text)
+    return text
+
+
+# Markdown constructs to drop when falling back to plain text.
+_STRIP_LINK_RE = re.compile(r"\[([^\]]+)\]\((?:https?://[^\s)]+)\)")
+_STRIP_HEADING_RE = re.compile(r"^\s{0,3}#{1,6}\s+", re.MULTILINE)
+# Only unwrap *paired* emphasis/code delimiters so literal characters
+# (e.g. ``svc_1``, ``*.py``, ``a*b``) are preserved rather than deleted.
+_STRIP_BOLD_RE = re.compile(r"(\*\*|__)(?=\S)(.+?)(?<=\S)\1", re.DOTALL)
+_STRIP_ITALIC_RE = re.compile(r"(?<![*_\w])([*_])(?=\S)(.+?)(?<=\S)\1(?![*_\w])")
+_STRIP_CODE_RE = re.compile(r"`([^`]+)`")
+
+
+def strip_markdown(text: str) -> str:
+    """Reduce markdown to readable plain text (safe fallback).
+
+    Unwraps *paired* emphasis/code spans and heading hashes and unwraps links
+    to their label, so a reply reads cleanly on a platform whose dialect we
+    don't specifically target. Unpaired or literal delimiters (``svc_1``,
+    ``*.py``, ``a*b``) are left untouched so identifiers and code are never
+    corrupted.
+    """
+    if not text:
+        return ""
+    text = _STRIP_LINK_RE.sub(r"\1", text)
+    text = _STRIP_HEADING_RE.sub("", text)
+    text = _STRIP_CODE_RE.sub(r"\1", text)
+    text = _STRIP_BOLD_RE.sub(r"\2", text)
+    text = _STRIP_ITALIC_RE.sub(r"\2", text)
+    return text
+
+
+def format_for_dialect(text: str, dialect: str) -> Tuple[str, Optional[str]]:
+    """Render ``text`` for a platform's declared ``markdown_dialect``.
+
+    Args:
+        text: The agent's reply text, authored in ordinary markdown.
+        dialect: The platform's ``markdown_dialect`` capability value.
+
+    Returns:
+        ``(rendered_text, parse_mode)`` — ``parse_mode`` is the value the
+        transport expects (e.g. ``"MarkdownV2"`` for Telegram) or ``None`` when
+        the text is already in the platform's native form / plain text.
+    """
+    if text is None:
+        return ("", None)
+    if dialect == "telegram_markdown_v2":
+        return (escape_markdown_v2(text), "MarkdownV2")
+    if dialect == "slack":
+        return (markdown_to_slack(text), None)
+    if dialect == "discord_markdown":
+        return (text, None)
+    # "markdown" / unknown: safe plain-text fallback.
+    return (strip_markdown(text), None)
@@ -15,7 +15,16 @@ import hashlib
 import time
 from dataclasses import dataclass, field
 from enum import Enum
-from typing import TYPE_CHECKING, Any, Dict, List, Literal, Optional, Union
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Dict,
+    List,
+    Literal,
+    Optional,
+    Tuple,
+    Union,
+)

 if TYPE_CHECKING:
    from .protocols import CallbackPayloadStoreProtocol
@@ -76,6 +85,8 @@ class BlockType(str, Enum):
    SELECT = "select"        # Dropdown/select menu
    DIVIDER = "divider"      # Visual separator
    CONTEXT = "context"      # Contextual info (smaller text)
+    TABLE = "table"          # Tabular data (columns + rows)
+    CHART = "chart"          # Chart/visualisation (kind + series)


@dataclass
@@ -245,6 +256,12 @@ class PresentationBlock:
    options: Optional[List[SelectOption]] = None
    placeholder: Optional[str] = None
    action_id: Optional[str] = None
+    # Tabular data (TABLE blocks)
+    columns: Optional[List[str]] = None
+    rows: Optional[List[List[str]]] = None
+    # Chart data (CHART blocks)
+    chart_kind: Optional[str] = None
+    series: Optional[List[Dict[str, Any]]] = None
    
    @staticmethod
    def make_text(content: str, markdown: bool = True) -> "PresentationBlock":
@@ -280,6 +297,47 @@ class PresentationBlock:
        """Create a context block (smaller text)."""
        return PresentationBlock(type=BlockType.CONTEXT, text=content)

+    @staticmethod
+    def make_table(
+        columns: List[str],
+        rows: List[List[str]],
+    ) -> "PresentationBlock":
+        """Create a table block from *columns* and *rows*.
+
+        Describe tabular data once; channels with a native table widget render
+        it directly, and everywhere else it degrades to a deterministic
+        markdown table (see :func:`adapt_presentation`).
+        """
+        return PresentationBlock(
+            type=BlockType.TABLE,
+            columns=[str(c) for c in columns],
+            rows=[[str(c) for c in row] for row in rows],
+        )
+
+    @staticmethod
+    def make_chart(
+        chart_kind: str,
+        series: List[Dict[str, Any]],
+        text: Optional[str] = None,
+    ) -> "PresentationBlock":
+        """Create a chart block.
+
+        Args:
+            chart_kind: One of ``"bar"``, ``"line"``, ``"pie"``, ``"area"``.
+            series: A list of ``{"label": str, "points": list[float]}`` dicts.
+            text: Optional caption/title for the chart.
+
+        Channels with native visualisation render the series directly; elsewhere
+        the chart degrades to a compact text summary (see
+        :func:`adapt_presentation`).
+        """
+        return PresentationBlock(
+            type=BlockType.CHART,
+            chart_kind=chart_kind,
+            series=series,
+            text=text,
+        )
+
    @staticmethod
    def quick_replies(
        choices: List[Any],
@@ -320,6 +378,14 @@ class PresentationBlock:
            data["placeholder"] = self.placeholder
        if self.action_id is not None:
            data["action_id"] = self.action_id
+        if self.columns is not None:
+            data["columns"] = self.columns
+        if self.rows is not None:
+            data["rows"] = self.rows
+        if self.chart_kind is not None:
+            data["chart_kind"] = self.chart_kind
+        if self.series is not None:
+            data["series"] = self.series
        return data
    
    @classmethod
@@ -338,6 +404,10 @@ class PresentationBlock:
            ),
            placeholder=data.get("placeholder"),
            action_id=data.get("action_id"),
+            columns=data.get("columns"),
+            rows=data.get("rows"),
+            chart_kind=data.get("chart_kind"),
+            series=data.get("series"),
        )


@@ -484,6 +554,10 @@ class PresentationLimits:
        supports_markdown: Whether channel supports markdown
        supports_select: Whether channel supports select menus
        supports_web_apps: Whether channel supports web apps
+        supports_tables: Whether channel has a native table widget
+        supports_charts: Whether channel has native chart/visualisation
+        max_table_rows: Maximum rows in a table block
+        max_table_cols: Maximum columns in a table block
    """
    
    max_buttons: int = 10
@@ -495,6 +569,10 @@ class PresentationLimits:
    supports_markdown: bool = True
    supports_select: bool = True
    supports_web_apps: bool = False
+    supports_tables: bool = False
+    supports_charts: bool = False
+    max_table_rows: int = 50
+    max_table_cols: int = 10
    
    def to_dict(self) -> Dict[str, Any]:
        """Convert to dictionary for serialization."""
@@ -508,6 +586,10 @@ class PresentationLimits:
            "supports_markdown": self.supports_markdown,
            "supports_select": self.supports_select,
            "supports_web_apps": self.supports_web_apps,
+            "supports_tables": self.supports_tables,
+            "supports_charts": self.supports_charts,
+            "max_table_rows": self.max_table_rows,
+            "max_table_cols": self.max_table_cols,
        }
    
    @classmethod
@@ -523,6 +605,10 @@ class PresentationLimits:
            supports_markdown=data.get("supports_markdown", True),
            supports_select=data.get("supports_select", True),
            supports_web_apps=data.get("supports_web_apps", False),
+            supports_tables=data.get("supports_tables", False),
+            supports_charts=data.get("supports_charts", False),
+            max_table_rows=data.get("max_table_rows", 50),
+            max_table_cols=data.get("max_table_cols", 10),
        )
    
    @staticmethod
@@ -758,6 +844,80 @@ def _select_to_buttons(
    return PresentationBlock(type=BlockType.BUTTONS, buttons=buttons)


+def _clamp_table(
+    block: PresentationBlock,
+    limits: PresentationLimits,
+) -> PresentationBlock:
+    """Return a copy of a TABLE block clamped to the channel's row/column caps."""
+    columns = list(block.columns or [])
+    rows = [list(r) for r in (block.rows or [])]
+    if limits.max_table_cols and len(columns) > limits.max_table_cols:
+        columns = columns[: limits.max_table_cols]
+        rows = [r[: limits.max_table_cols] for r in rows]
+    if limits.max_table_rows and len(rows) > limits.max_table_rows:
+        rows = rows[: limits.max_table_rows]
+    return PresentationBlock(type=BlockType.TABLE, columns=columns, rows=rows)
+
+
+def table_to_markdown(columns: List[str], rows: List[List[str]]) -> str:
+    """Render a table as a deterministic GitHub-flavoured markdown table.
+
+    Cells are coerced to strings and pipes escaped so the table stays valid.
+    Short rows are padded and long rows trimmed to the header width.
+    """
+    def _cell(value: Any) -> str:
+        return str(value).replace("|", "\\|").replace("\n", " ")
+
+    header = [_cell(c) for c in columns]
+    ncols = len(header)
+    lines = ["| " + " | ".join(header) + " |"]
+    lines.append("| " + " | ".join(["---"] * ncols) + " |")
+    for row in rows:
+        cells = [_cell(c) for c in row][:ncols]
+        cells += [""] * (ncols - len(cells))
+        lines.append("| " + " | ".join(cells) + " |")
+    return "\n".join(lines)
+
+
+def chart_to_text(
+    chart_kind: Optional[str],
+    series: List[Dict[str, Any]],
+    caption: Optional[str] = None,
+) -> str:
+    """Render a chart as a compact, deterministic text summary.
+
+    Produces a caption/kind header followed by one line per series listing its
+    label and points, so the data is never silently dropped on channels without
+    a native visualisation.
+    """
+    lines: List[str] = []
+    kind = chart_kind or "chart"
+    header = caption or f"{kind.capitalize()} chart"
+    lines.append(header)
+    for entry in series or []:
+        label = str(entry.get("label", "series"))
+        points = entry.get("points", []) or []
+        rendered = ", ".join(str(p) for p in points)
+        lines.append(f"{label}: {rendered}")
+    return "\n".join(lines)
+
+
+def _table_to_text_block(block: PresentationBlock) -> PresentationBlock:
+    """Degrade a TABLE block to a markdown-table TEXT block."""
+    return PresentationBlock(
+        type=BlockType.TEXT,
+        text=table_to_markdown(block.columns or [], block.rows or []),
+    )
+
+
+def _chart_to_text_block(block: PresentationBlock) -> PresentationBlock:
+    """Degrade a CHART block to a text-summary TEXT block."""
+    return PresentationBlock(
+        type=BlockType.TEXT,
+        text=chart_to_text(block.chart_kind, block.series or [], block.text),
+    )
+
+
 def adapt_presentation(
    presentation: MessagePresentation,
    limits: PresentationLimits,
@@ -868,6 +1028,43 @@ def adapt_presentation(
            )
            continue

+        if block_type == BlockType.TABLE.value:
+            clamped = _clamp_table(block, limits)
+            if limits.supports_tables:
+                adapted_blocks.append(clamped)
+            else:
+                # Degrade to a deterministic markdown table (then clamp text).
+                text_block = _table_to_text_block(clamped)
+                if (
+                    limits.max_text_length
+                    and text_block.text
+                    and len(text_block.text) > limits.max_text_length
+                ):
+                    text_block = PresentationBlock(
+                        type=BlockType.TEXT,
+                        text=text_block.text[: limits.max_text_length],
+                    )
+                adapted_blocks.append(text_block)
+            continue
+
+        if block_type == BlockType.CHART.value:
+            if limits.supports_charts:
+                adapted_blocks.append(block)
+            else:
+                # Degrade to a compact text summary (then clamp text).
+                text_block = _chart_to_text_block(block)
+                if (
+                    limits.max_text_length
+                    and text_block.text
+                    and len(text_block.text) > limits.max_text_length
+                ):
+                    text_block = PresentationBlock(
+                        type=BlockType.TEXT,
+                        text=text_block.text[: limits.max_text_length],
+                    )
+                adapted_blocks.append(text_block)
+            continue
+
        adapted_blocks.append(block)

    return MessagePresentation(
@@ -878,3 +1075,257 @@ def adapt_presentation(
    )


+# Machine-readable degradation reason codes, mirroring the ``REASON_*`` style in
+# ``admission.py``/``failure.py`` so a dropped control is recorded, not silent.
+DEGRADE_SELECT_UNSUPPORTED = "select_unsupported"
+DEGRADE_WEB_APP_UNAVAILABLE = "web_app_unavailable"
+DEGRADE_BUTTONS_TRUNCATED = "buttons_truncated"
+DEGRADE_OPTIONS_TRUNCATED = "options_truncated"
+DEGRADE_TABLE_AS_TEXT = "table_rendered_as_text"
+DEGRADE_CHART_AS_TEXT = "chart_rendered_as_text"
+DEGRADE_CALLBACK_DATA_TOO_LONG = "callback_data_too_long"
+
+
+@dataclass(frozen=True)
+class DegradedDelivery:
+    """A record of controls a channel could not render natively.
+
+    ``adapt_presentation`` already downgrades charts/tables/buttons/selects to
+    deterministic text/callbacks, but returns *no record* of what it dropped, so
+    the downgrade is silent — the user (and the model) never learns a button
+    vanished or a chart became text. This is the typed report of that
+    degradation, the presentation-path counterpart of
+    :class:`~praisonaiagents.bots.failure.FailureReply`: an adapter appends
+    :attr:`fallback_text` so the loss is *visible*, and records
+    :attr:`reasons` so it is *machine-readable*.
+
+    Attributes:
+        dropped: Human-readable descriptions of each degraded/dropped control
+            (e.g. ``"1 button rendered as text"``).
+        reasons: Machine-readable reason codes (the ``DEGRADE_*`` constants),
+            aligned by intent with ``dropped``.
+        fallback_text: A short, user-facing note the adapter can append so the
+            degradation is never silent (e.g. ``"(Delivered 1 button as text -
+            Telegram callback data exceeded 64 bytes.)"``). Empty when nothing
+            degraded.
+    """
+
+    dropped: Tuple[str, ...]
+    reasons: Tuple[str, ...]
+    fallback_text: str
+
+
+def _callback_is_lossy(value: Optional[str]) -> bool:
+    """True when an *adapted* callback value carries the lossy hash marker.
+
+    :func:`_encode_reply_callback` / :func:`_encode_select_callback` emit a
+    ``#<digest>`` payload only when the original value overflowed the channel
+    byte-cap *and* no store was available to preserve it losslessly. Detecting
+    that marker on the already-adapted value is the single source of truth for
+    "callback data too long" — so the report never disagrees with the
+    adaptation (e.g. no false positive when a store round-trips the value, and
+    no miss for a degraded select option).
+    """
+    if not value:
+        return False
+    if value.startswith(f"{REPLY_CALLBACK_PREFIX}{REPLY_HASH_MARKER}"):
+        return True
+    # Degraded select options: ``select:...:`` with no ``@<ref>`` store marker
+    # means the value was hashed (lossy). A stored ref carries CALLBACK_REF_MARKER.
+    if value.startswith("select:"):
+        tail = value.rsplit(":", 1)[-1]
+        return not tail.startswith(CALLBACK_REF_MARKER)
+    return False
+
+
+def _presentation_degradation(
+    presentation: MessagePresentation,
+    limits: PresentationLimits,
+    callback_store: Optional["CallbackPayloadStoreProtocol"] = None,
+) -> Optional[DegradedDelivery]:
+    """Compute the :class:`DegradedDelivery` report for adapting to ``limits``.
+
+    Derives the report from the *same* conversion and selection decisions as
+    :func:`adapt_presentation` (select->buttons, priority/cap button truncation,
+    web_app->url, option truncation, table/chart->text) — inspecting only the
+    controls actually retained and reporting callback shortening only when the
+    adapter genuinely produced a lossy payload. Returns ``None`` when nothing
+    degrades.
+    """
+    dropped: List[str] = []
+    reasons: List[str] = []
+
+    for block in presentation.blocks:
+        block_type = block.type.value if isinstance(block.type, BlockType) else block.type
+
+        if block_type == BlockType.SELECT.value and not limits.supports_select:
+            # Follow the adapter: select -> buttons (encoding option callbacks
+            # exactly as adapt_presentation does), then treat as a buttons block.
+            n = len(block.options or [])
+            dropped.append(f"select menu ({n} options) rendered as buttons")
+            reasons.append(DEGRADE_SELECT_UNSUPPORTED)
+            block = _select_to_buttons(block, callback_store)
+            block_type = BlockType.BUTTONS.value
+
+        if block_type == BlockType.BUTTONS.value and block.buttons:
+            buttons = list(block.buttons)
+            rows = limits.max_button_rows if limits.max_button_rows else 1
+            total_cap = limits.max_buttons * rows if limits.max_buttons else len(buttons)
+            if total_cap <= 0:
+                total_cap = len(buttons)
+            if len(buttons) > total_cap:
+                n = len(buttons) - total_cap
+                dropped.append(f"{n} button(s) dropped (over channel cap)")
+                reasons.append(DEGRADE_BUTTONS_TRUNCATED)
+                # Only the *retained* buttons are actually rendered; mirror the
+                # priority-aware selection so we don't report a dropped
+                # button's web_app/callback degradation.
+                indexed = list(enumerate(buttons))
+                kept = sorted(
+                    indexed, key=lambda iv: (iv[1].priority, -iv[0]), reverse=True
+                )[:total_cap]
+                kept.sort(key=lambda iv: iv[0])
+                buttons = [b for _, b in kept]
+
+            for btn in buttons:
+                if btn.action is None:
+                    continue
+                # Compare against the adapter's actual output for this button.
+                adapted_btn = _adapt_button(btn, limits, callback_store)
+                a_type = (
+                    btn.action.type.value
+                    if isinstance(btn.action.type, ActionType)
+                    else btn.action.type
+                )
+                if (
+                    not limits.supports_web_apps
+                    and a_type == ActionType.WEB_APP.value
+                    and btn.action.web_app_url
+                ):
+                    dropped.append("web-app button rendered as URL")
+                    reasons.append(DEGRADE_WEB_APP_UNAVAILABLE)
+                elif adapted_btn.action is not None and _callback_is_lossy(
+                    adapted_btn.action.value
+                ):
+                    dropped.append("button callback shortened (data exceeded byte cap)")
+                    reasons.append(DEGRADE_CALLBACK_DATA_TOO_LONG)
+
+        elif block_type == BlockType.SELECT.value and block.options:
+            if limits.max_options and len(block.options) > limits.max_options:
+                n = len(block.options) - limits.max_options
+                dropped.append(f"{n} select option(s) dropped (over channel cap)")
+                reasons.append(DEGRADE_OPTIONS_TRUNCATED)
+
+        elif block_type == BlockType.TABLE.value and not limits.supports_tables:
+            dropped.append("table rendered as text")
+            reasons.append(DEGRADE_TABLE_AS_TEXT)
+
+        elif block_type == BlockType.CHART.value and not limits.supports_charts:
+            dropped.append("chart rendered as text")
+            reasons.append(DEGRADE_CHART_AS_TEXT)
+
+    if not dropped:
+        return None
+
+    fallback_text = "(" + "; ".join(dropped) + ".)"
+    return DegradedDelivery(
+        dropped=tuple(dropped),
+        reasons=tuple(reasons),
+        fallback_text=fallback_text,
+    )
+
+
+def adapt_presentation_with_report(
+    presentation: MessagePresentation,
+    limits: PresentationLimits,
+    *,
+    callback_store: Optional["CallbackPayloadStoreProtocol"] = None,
+) -> "tuple[MessagePresentation, Optional[DegradedDelivery]]":
+    """Adapt a presentation *and* report what degraded.
+
+    Identical to :func:`adapt_presentation` for the returned presentation, but
+    additionally returns a typed :class:`DegradedDelivery` (or ``None``) so the
+    adapter can append a readable text fallback and record machine-readable
+    reasons instead of downgrading silently. ``adapt_presentation`` is retained
+    unchanged for callers that do not need the report.
+
+    Returns:
+        ``(adapted_presentation, degraded_or_none)``.
+    """
+    adapted = adapt_presentation(presentation, limits, callback_store=callback_store)
+    report = _presentation_degradation(presentation, limits, callback_store)
+    return adapted, report
+
+
+# The renderer contract lives in ``protocols.py`` (alongside the other bot
+# extension-point protocols). Re-exported here for backward-compatible imports
+# (``from praisonaiagents.bots.presentation import PresentationRendererProtocol``).
+from .protocols import PresentationRendererProtocol  # noqa: E402,F401
+
+
+# Registry keyed by a normalized (lowercased, stripped) platform id. Both
+# built-in (registered by the wrapper at import time) and plugin renderers
+# register here identically, so no channel is second-class for interactive UX.
+# Consumers resolve with ``get_presentation_renderer`` and fall back to plain
+# text only when genuinely no renderer exists for a platform.
+_PRESENTATION_RENDERERS: Dict[str, type] = {}
+
+
+def _normalize_platform(platform: str) -> str:
+    """Normalize a platform id the same way the channel registry does.
+
+    Channel identifiers are matched case-insensitively elsewhere, so a
+    mixed-case plugin id (``"Matrix"``) must resolve to the same renderer slot
+    as ``"matrix"``. Without this, a channel could register/resolve as a channel
+    but silently miss its renderer and degrade to plain text.
+    """
+    return platform.strip().lower()
+
+
+def register_presentation_renderer(platform: str, renderer: type) -> None:
+    """Register *renderer* as the presentation renderer for *platform*.
+
+    Any channel — built-in or a pip-installed plugin — calls this (e.g. from its
+    ``setup`` hook or entry point) so its interactive presentations render
+    natively instead of degrading to plain text. Re-registering a platform
+    overrides the previous renderer, letting a plugin intentionally supersede a
+    built-in.
+
+    Args:
+        platform: The channel/platform id (e.g. ``"telegram"``, ``"matrix"``);
+            matched case-insensitively.
+        renderer: A class satisfying :class:`PresentationRendererProtocol`
+            (exposing ``get_limits`` and ``render``).
+
+    Raises:
+        ValueError: If *platform* is empty/blank.
+        TypeError: If *renderer* does not expose callable ``get_limits`` and
+            ``render`` — so a misconfigured renderer fails loudly at
+            registration rather than later inside :func:`render_for`.
+    """
+    key = _normalize_platform(platform) if isinstance(platform, str) else ""
+    if not key:
+        raise ValueError(
+            "register_presentation_renderer: platform id must be a non-empty "
+            "string (e.g. 'telegram', 'matrix')."
+        )
+    if not (callable(getattr(renderer, "get_limits", None))
+            and callable(getattr(renderer, "render", None))):
+        raise TypeError(
+            "register_presentation_renderer: renderer for "
+            f"'{platform}' must satisfy PresentationRendererProtocol — expose "
+            "static/callable 'get_limits()' and 'render(presentation)'."
+        )
+    _PRESENTATION_RENDERERS[key] = renderer
+
+
+def get_presentation_renderer(platform: str) -> Optional[type]:
+    """Return the registered renderer class for *platform*, or ``None``.
+
+    Lookup is case-insensitive to mirror registration.
+    """
+    if not isinstance(platform, str):
+        return None
+    return _PRESENTATION_RENDERERS.get(_normalize_platform(platform))
+
+
@@ -302,6 +302,79 @@ class WebhookVerifierProtocol(Protocol):
        ...


+class GatewayAdapterContractError(TypeError):
+    """Raised when a channel adapter cannot receive the gateway runtime seams.
+
+    The gateway wires four reliability seams into every channel adapter —
+    the cross-platform identity resolver, the delivery router, the admission
+    gate, and the shared per-turn lock map. When the gateway has these seams
+    to inject but the adapter neither implements
+    :class:`SupportsGatewayRuntime` nor exposes a compatible session, the wiring
+    would silently no-op and the adapter would run without admission control,
+    durable delivery routing, or cross-platform turn locking. Failing loudly
+    with this error surfaces the missing contract instead.
+    """
+
+
+@dataclass
+class GatewayRuntimeSeams:
+    """The gateway reliability seams handed to a channel adapter at build time.
+
+    A single, typed carrier for the four runtime seams the gateway injects so
+    an adapter wires them up in one place instead of via four duck-typed
+    private-attribute splices:
+
+    Attributes:
+        identity_resolver: Cross-platform identity resolver; unifies the same
+            human across platforms onto one session key.
+        delivery_router: Backing router for the built-in ``send_message`` tool,
+            so an agent turn can proactively reach the user mid-task.
+        admission_gate: Gateway-wide admission control (concurrency ceiling /
+            fair queue / backpressure) applied to inbound runs.
+        turn_lock_map: Shared per-turn lock map for cross-platform turn
+            serialisation on the resolved session id.
+
+    A seam left ``None`` means the gateway has nothing to inject for it and the
+    adapter should keep whatever it already has.
+    """
+
+    identity_resolver: Optional[Any] = None
+    delivery_router: Optional[Any] = None
+    admission_gate: Optional[Any] = None
+    turn_lock_map: Optional[Any] = None
+
+
+@runtime_checkable
+class SupportsGatewayRuntime(Protocol):
+    """Contract for channel adapters that accept the gateway runtime seams.
+
+    Instead of the gateway reaching into an adapter's private session and
+    splicing ``_identity_resolver`` / ``_delivery_router`` / ``_admission_gate``
+    / ``_locks`` via ``getattr``/``hasattr`` (which silently no-ops on any
+    adapter whose session does not match the built-in shape), an adapter — in
+    tree or ``pip``-installed — implements this one method. The gateway calls it
+    once with a :class:`GatewayRuntimeSeams`, so the same reliability guarantees
+    (admission/backpressure, delivery routing, cross-platform turn locking)
+    hold for *every* adapter.
+
+    Adapters whose ``__init__`` creates a ``BotSessionManager`` get this for
+    free — the session manager implements ``attach_gateway_runtime`` and the
+    adapter can simply delegate to ``self._session.attach_gateway_runtime(...)``.
+    """
+
+    def attach_gateway_runtime(self, runtime: "GatewayRuntimeSeams") -> None:
+        """Wire the gateway runtime seams into this adapter.
+
+        Only seams present (non-``None``) on ``runtime`` should be applied;
+        seams left ``None`` mean the gateway has nothing to inject and the
+        adapter must keep its existing value.
+
+        Args:
+            runtime: The gateway reliability seams to attach.
+        """
+        ...
+
+
 class MessageType(str, Enum):
    """Types of bot messages."""
    
@@ -1112,6 +1185,34 @@ class SupportsPresentation(Protocol):
        ...


+@runtime_checkable
+class PresentationRendererProtocol(Protocol):
+    """Contract a channel presentation renderer implements.
+
+    A renderer converts a portable :class:`MessagePresentation` into a native,
+    platform-specific payload (Telegram inline keyboard, Slack blocks, …). It
+    should run ``adapt_presentation`` against its own :meth:`get_limits` first
+    so capability-driven degradation is applied uniformly.
+
+    This protocol is the core seam that lets *any* channel — built-in or a
+    pip-installed plugin — register a native renderer via
+    ``register_presentation_renderer``, mirroring how a channel already
+    contributes config via :class:`ChannelDescriptor`. Heavy renderer
+    implementations still live in ``praisonai-bot``; only the contract and the
+    registry live in core.
+    """
+
+    @staticmethod
+    def get_limits() -> "PresentationLimits":
+        """Return this channel's capability limits."""
+        ...
+
+    @staticmethod
+    def render(presentation: "MessagePresentation") -> Dict[str, Any]:
+        """Render *presentation* into a native, platform-specific payload."""
+        ...
+
+
 # ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 # EmailProtocol — email-specific bot capabilities
 # ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
@@ -66,6 +66,39 @@ def is_intentional_silence_response(text: str | None) -> bool:
    return False


+def classify_final(text: str | None) -> str:
+    """Classify an agent's final reply for the visible-outcome guarantee.
+
+    Every inbound turn must end in a visible outcome or a recorded, intentional
+    non-outcome. This is the single decision point the bot/gateway layer uses to
+    tell those apart, so no adapter re-decides "blank" differently:
+
+      - ``"silence"``: a deliberate no-reply (an exact ``NO_REPLY``/``[SILENT]``
+        marker). The gateway suppresses the send on purpose.
+      - ``"empty"``: blank, whitespace-only, or the machine ``[tool_calls: …]``
+        placeholder — NOT deliberate silence. The gateway must substitute a
+        recorded, user-facing fallback rather than drop it or leak the token.
+      - ``"text"``: real user-facing content to deliver as-is.
+
+    Examples:
+        >>> classify_final("NO_REPLY")
+        'silence'
+        >>> classify_final("")
+        'empty'
+        >>> classify_final("   ")
+        'empty'
+        >>> classify_final("[tool_calls: search_web]")
+        'empty'
+        >>> classify_final("Here is your answer.")
+        'text'
+    """
+    if is_intentional_silence_response(text):
+        return "silence"
+    if not text or not text.strip() or text.strip().startswith("[tool_calls:"):
+        return "empty"
+    return "text"
+
+
@dataclass
 class BotLoopPolicy:
    """Sliding-window pair budget for bot-to-bot loop protection.
@@ -0,0 +1,197 @@
+"""Declarative webhook filter — a tiny, import-light matcher for HTTP events.
+
+A generic webhook channel needs to decide, purely from configuration, whether
+an inbound HTTP event should trigger an agent. This module provides that
+decision as a small, side-effect-free predicate tree so the heavy HTTP-serving
+ingress (in ``praisonai-bot``) — and any third-party channel — can reuse one
+canonical filter semantics instead of re-implementing payload matching.
+
+The filter is expressed as plain dict/JSON so it round-trips through YAML:
+
+    when:
+      all:
+        - { field: headers.X-GitHub-Event, equals: issues }
+        - { field: payload.action, in: [opened, reopened] }
+
+Grammar
+-------
+A node is either a *combinator* or a *leaf*.
+
+Combinators (compose sub-nodes)::
+
+    {"all": [<node>, ...]}   # AND — every child must match (empty = True)
+    {"any": [<node>, ...]}   # OR  — at least one child matches (empty = False)
+    {"not": <node>}          # negation
+
+Leaf (a single field test)::
+
+    {"field": "payload.action", "<op>": <value>}
+
+where ``<op>`` is one of:
+
+- ``exists``  — truthy check the field is present (value: bool, default True)
+- ``equals``  — equality (string-insensitive for headers is *not* implied;
+                 compares the resolved value to ``value``)
+- ``contains``— substring / membership (``value in resolved``)
+- ``in``      — resolved value is one of ``value`` (a list)
+- ``regex``   — ``re.search(value, str(resolved))``
+
+``field`` is a dotted path into the event mapping, e.g. ``payload.issue.number``
+or ``headers.X-GitHub-Event``. Header lookup is case-insensitive. A missing path
+resolves to ``None`` and simply fails the leaf (fail-safe), it never raises.
+
+This module has no third-party imports and does not perform any I/O, so it is
+safe to keep in the core SDK; the wrapper composes it with HMAC verification and
+the ingress journal.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any, Mapping, Optional
+
+__all__ = ["WebhookFilter", "evaluate_webhook_filter", "resolve_field"]
+
+
+def resolve_field(event: Mapping[str, Any], path: str) -> Any:
+    """Resolve a dotted ``path`` into ``event``, case-insensitively for headers.
+
+    Args:
+        event: The normalised event mapping, typically
+            ``{"payload": ..., "headers": ..., "query": ...}``.
+        path: A dotted path like ``payload.issue.number`` or
+            ``headers.X-GitHub-Event``.
+
+    Returns:
+        The resolved value, or ``None`` if any segment is missing. Never raises.
+    """
+    if not path:
+        return None
+    parts = path.split(".")
+    current: Any = event
+    header_section = parts[0] == "headers"
+    for i, part in enumerate(parts):
+        if isinstance(current, Mapping):
+            if part in current:
+                current = current[part]
+                continue
+            # Headers are case-insensitive: fall back to a lowered-key match for
+            # the segment directly under ``headers``.
+            if header_section and i == 1:
+                lowered = {str(k).lower(): v for k, v in current.items()}
+                if part.lower() in lowered:
+                    current = lowered[part.lower()]
+                    continue
+            return None
+        return None
+    return current
+
+
+def _match_leaf(event: Mapping[str, Any], node: Mapping[str, Any]) -> bool:
+    """Evaluate a single ``{"field": ..., "<op>": value}`` leaf. Fail-safe."""
+    field = node.get("field")
+    if not isinstance(field, str):
+        return False
+    resolved = resolve_field(event, field)
+
+    if "exists" in node:
+        want = node["exists"]
+        present = resolved is not None
+        return present if bool(want) else (not present)
+
+    if "equals" in node:
+        return resolved == node["equals"]
+
+    if "contains" in node:
+        needle = node["contains"]
+        try:
+            return needle in resolved  # type: ignore[operator]
+        except TypeError:
+            return False
+
+    if "in" in node:
+        options = node["in"]
+        if isinstance(options, (list, tuple, set)):
+            return resolved in options
+        return False
+
+    if "regex" in node:
+        pattern = node["regex"]
+        if not isinstance(pattern, str) or resolved is None:
+            return False
+        try:
+            return re.search(pattern, str(resolved)) is not None
+        except re.error:
+            return False
+
+    # A leaf with only ``field`` and no operator is treated as an existence
+    # check — matches when the field is present.
+    return resolved is not None
+
+
+def evaluate_webhook_filter(
+    event: Mapping[str, Any], node: Optional[Any]
+) -> bool:
+    """Evaluate a declarative filter ``node`` against a normalised ``event``.
+
+    Args:
+        event: Normalised event, e.g. ``{"payload", "headers", "query"}``.
+        node: The filter tree (dict). ``None`` or ``{}`` matches everything so a
+            route with no ``when`` is an unconditional catch-all.
+
+    Returns:
+        True if the event matches. Never raises on malformed input — an
+        unrecognised node fails closed to ``False`` (except the empty/None
+        catch-all above).
+    """
+    if node is None or node == {}:
+        return True
+    if not isinstance(node, Mapping):
+        return False
+
+    if "all" in node:
+        children = node["all"] or []
+        return all(evaluate_webhook_filter(event, c) for c in children)
+    if "any" in node:
+        children = node["any"] or []
+        return any(evaluate_webhook_filter(event, c) for c in children)
+    if "not" in node:
+        return not evaluate_webhook_filter(event, node["not"])
+
+    if "field" in node:
+        return _match_leaf(event, node)
+
+    return False
+
+
+class WebhookFilter:
+    """A reusable, config-driven predicate over a normalised webhook event.
+
+    Wraps a declarative filter tree so callers can validate it once and match
+    many events::
+
+        f = WebhookFilter({"all": [
+            {"field": "headers.X-GitHub-Event", "equals": "issues"},
+            {"field": "payload.action", "in": ["opened", "reopened"]},
+        ]})
+        if f.matches({"headers": {...}, "payload": {...}}):
+            ...
+
+    A ``None``/empty tree is an unconditional match (catch-all route).
+    """
+
+    __slots__ = ("_tree",)
+
+    def __init__(self, tree: Optional[Any] = None) -> None:
+        self._tree = tree
+
+    @property
+    def tree(self) -> Optional[Any]:
+        return self._tree
+
+    def matches(self, event: Mapping[str, Any]) -> bool:
+        """Return whether ``event`` satisfies the filter tree."""
+        return evaluate_webhook_filter(event, self._tree)
+
+    def __repr__(self) -> str:  # pragma: no cover - trivial
+        return f"WebhookFilter({self._tree!r})"
@@ -5,7 +5,6 @@ Provides publish/subscribe functionality for typed events.
 """

 import asyncio
-import logging
 from praisonaiagents._logging import get_logger
 import threading
 from typing import Any, Callable, Dict, List, Optional, Set, Union
@@ -7,7 +7,6 @@ Implements shadow git repository for file-level checkpointing.
 import os
 import re
 import asyncio
-import logging
 from praisonaiagents._logging import get_logger
 import shutil
 from typing import Optional, List, Dict, Any, Callable
@@ -37,6 +37,8 @@ __all__ = [
    "ToolResultPrunerProtocol",
    "MessageFormatterProtocol", 
    "SummaryBuilderProtocol",
+    # Read-only recap
+    "build_recap",
 ]


@@ -70,4 +72,8 @@ def __getattr__(name: str):
        from .protocols import SummaryBuilderProtocol
        return SummaryBuilderProtocol
    
+    if name == "build_recap":
+        from .recap import build_recap
+        return build_recap
+    
    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
@@ -160,7 +160,8 @@ class ContextCompactor:
                )
            except Exception:
                pass
-        return max(1, len(text) // 4)
+        from ..context.tokens import estimate_tokens_heuristic
+        return estimate_tokens_heuristic(text)

    def count_message_tokens(self, message: Dict[str, Any]) -> int:
        """Count tokens in a message, including tool_calls payloads."""
@@ -458,6 +459,58 @@ class ContextCompactor:
            return self.tool_pruner.prune(messages, self.config.max_tool_result_size)
        return messages, 0
    
+    def _snap_to_pair_boundary(
+        self,
+        messages: List[Dict[str, Any]],
+        cut_index: int,
+    ) -> int:
+        """Move ``cut_index`` so it never splits an assistant ``tool_calls``
+        message from its matching ``tool`` result.
+
+        ``messages[:cut_index]`` is the older segment that gets dropped or
+        summarised; ``messages[cut_index:]`` is the recent segment that is
+        kept verbatim. If the boundary would leave a ``tool`` result at the
+        head of the kept segment whose originating assistant ``tool_calls``
+        message sits in the older segment (or vice versa), strict providers
+        reject the transcript with a 400. This snaps the boundary *outward*
+        (to a lower index) so the whole pair is kept together on the recent
+        side, which is the safe direction for the provider contract.
+
+        Returns a boundary index in ``[0, len(messages)]``.
+        """
+        if cut_index <= 0 or cut_index >= len(messages):
+            return max(0, min(cut_index, len(messages)))
+
+        # Collect the tool_call ids produced by assistant messages that fall
+        # in the older (dropped/summarised) segment. Any tool result in the
+        # kept segment referencing one of these would be orphaned.
+        def _call_ids(msg: Dict[str, Any]) -> set:
+            ids = set()
+            for tc in (msg.get("tool_calls") or []):
+                if isinstance(tc, dict) and tc.get("id"):
+                    ids.add(tc["id"])
+            return ids
+
+        # Walk the boundary outward while the first kept message is an orphaned
+        # tool result, i.e. its tool_call_id was emitted before the cut.
+        older_call_ids = set()
+        for msg in messages[:cut_index]:
+            older_call_ids |= _call_ids(msg)
+
+        while cut_index > 0:
+            head = messages[cut_index]
+            head_response_id = head.get("tool_call_id")
+            if head.get("role") == "tool" and head_response_id in older_call_ids:
+                # Pull the boundary back to include the preceding message; keep
+                # going until the emitting assistant tool_calls message is on
+                # the kept side too.
+                cut_index -= 1
+                older_call_ids -= _call_ids(messages[cut_index])
+            else:
+                break
+
+        return cut_index
+
    def _truncate(self, messages: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
        """Truncate oldest messages."""
        result = []
@@ -475,25 +528,49 @@ class ContextCompactor:
        # Always keep system messages
        result.extend(system_msgs)
        
-        # Keep recent messages
-        recent = other_msgs[-self.preserve_recent:] if other_msgs else []
+        # Keep recent messages. Snap the boundary outward so a tool result at
+        # the head of the kept window is never orphaned from its assistant
+        # tool_calls message (strict providers 400 on an orphaned tool result).
+        if other_msgs and len(other_msgs) > self.preserve_recent:
+            cut = self._snap_to_pair_boundary(
+                other_msgs, len(other_msgs) - self.preserve_recent
+            )
+        else:
+            cut = 0
+        recent = other_msgs[cut:]
        
        # Add recent messages
        result.extend(recent)
        
-        # If still over limit, truncate more
+        # If still over limit, truncate more. Drop the whole leading tool pair
+        # together (an assistant tool_calls message plus its tool results) so we
+        # never leave an orphaned tool result at the head of the kept window.
        while self.count_total_tokens(result) > self.target_tokens and len(result) > 1:
-            # Remove oldest message (respecting preserve_system setting)
-            removed = False
+            # Find the oldest droppable (non-system when preserved) message.
+            start = None
            for i, msg in enumerate(result):
-                # Skip system messages only if preserve_system is True
                if not (self.preserve_system and msg.get("role") == "system"):
-                    result.pop(i)
-                    removed = True
+                    start = i
                    break
-            if not removed:
+            if start is None:
                # Only system messages remain but still over budget — stop to avoid infinite loop
                break
+
+            # If the oldest droppable message emits tool_calls, drop it together
+            # with all of its immediately-following tool results.
+            drop_ids = set()
+            for tc in (result[start].get("tool_calls") or []):
+                if isinstance(tc, dict) and tc.get("id"):
+                    drop_ids.add(tc["id"])
+            end = start + 1
+            while (
+                drop_ids
+                and end < len(result)
+                and result[end].get("role") == "tool"
+                and result[end].get("tool_call_id") in drop_ids
+            ):
+                end += 1
+            del result[start:end]
        
        return result
    
@@ -506,20 +583,25 @@ class ContextCompactor:
            if self.preserve_system and msg.get("role") == "system":
                result.append(msg)
        
-        # Add messages from end until we hit target
+        # Add messages from end until we hit target. Track the boundary index
+        # into non_system so we can snap it to keep tool pairs together.
        non_system = [m for m in messages if m.get("role") != "system"]
        
+        kept = 0
+        window: List[Dict[str, Any]] = []
        for msg in reversed(non_system):
-            if self.count_total_tokens(result + [msg]) <= self.target_tokens:
-                result.insert(len([m for m in result if m.get("role") == "system"]), msg)
+            if self.count_total_tokens(result + [msg] + window) <= self.target_tokens:
+                window.insert(0, msg)
+                kept += 1
            else:
                break
        
-        # Ensure messages are in order
-        system_msgs = [m for m in result if m.get("role") == "system"]
-        other_msgs = [m for m in result if m.get("role") != "system"]
+        # Snap the boundary outward so a tool result kept at the window head is
+        # not orphaned from its assistant tool_calls left outside the window.
+        cut = self._snap_to_pair_boundary(non_system, len(non_system) - kept)
+        window = non_system[cut:]
        
-        return system_msgs + other_msgs
+        return result + window
    
    def _summarize(self, messages: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
        """Summarize old messages (simplified version)."""
@@ -531,11 +613,16 @@ class ContextCompactor:
        
        result.extend(system_msgs)
        
-        # Keep recent messages
-        recent = other_msgs[-self.preserve_recent:]
-        
-        # Summarize older messages
-        older = other_msgs[:-self.preserve_recent] if len(other_msgs) > self.preserve_recent else []
+        # Choose the recent/older boundary by count, then snap it so a
+        # tool_calls message and its result are never split across it.
+        if len(other_msgs) > self.preserve_recent:
+            cut = self._snap_to_pair_boundary(
+                other_msgs, len(other_msgs) - self.preserve_recent
+            )
+        else:
+            cut = 0
+        recent = other_msgs[cut:]
+        older = other_msgs[:cut]
        
        if older:
            # Create a simple summary
@@ -579,9 +666,17 @@ class ContextCompactor:
        
        result.extend(system_msgs)
        
-        # Keep recent messages intact
-        recent = other_msgs[-self.preserve_recent:]
-        older = other_msgs[:-self.preserve_recent] if len(other_msgs) > self.preserve_recent else []
+        # Keep recent messages intact. Snap the boundary so a tool_calls
+        # message and its result are pruned/kept together (prune only rewrites
+        # tool-result *content*, but a snapped boundary keeps intent consistent).
+        if len(other_msgs) > self.preserve_recent:
+            cut = self._snap_to_pair_boundary(
+                other_msgs, len(other_msgs) - self.preserve_recent
+            )
+        else:
+            cut = 0
+        recent = other_msgs[cut:]
+        older = other_msgs[:cut]
        
        # Prune older messages
        for msg in older:
@@ -664,8 +759,15 @@ class ContextCompactor:
        
        result.extend(system_msgs)
        
-        # Keep recent messages
-        recent = other_msgs[-self.preserve_recent:]
+        # Keep recent messages, snapping the boundary so tool_calls/result
+        # pairs are never split across the recent/older divide.
+        if len(other_msgs) > self.preserve_recent:
+            recent_cut = self._snap_to_pair_boundary(
+                other_msgs, len(other_msgs) - self.preserve_recent
+            )
+        else:
+            recent_cut = 0
+        recent = other_msgs[recent_cut:]
        
        # Determine what to summarize
        total_original_messages = len(messages)
@@ -677,13 +779,14 @@ class ContextCompactor:
            messages_since_summary = total_original_messages - self._previous_summary_global_idx
            new_older_messages = max(0, messages_since_summary - self.preserve_recent)
            if new_older_messages > 0:
-                to_summarize = other_msgs[-messages_since_summary:-self.preserve_recent]
+                to_summarize = other_msgs[-messages_since_summary:recent_cut]
            else:
                to_summarize = []
            self._used_previous_summary = True
        else:
-            # Fresh summary: summarize all older messages
-            to_summarize = other_msgs[:-self.preserve_recent] if len(other_msgs) > self.preserve_recent else []
+            # Fresh summary: summarize all older messages (kept in sync with the
+            # snapped recent boundary so a tool pair is never split)
+            to_summarize = other_msgs[:recent_cut]
            self._used_previous_summary = False
        
        if to_summarize or self._previous_summary:
@@ -774,8 +877,15 @@ class ContextCompactor:
        
        result.extend(system_msgs)
        
-        # Keep recent messages
-        recent = other_msgs[-self.preserve_recent:]
+        # Keep recent messages, snapping the boundary so tool_calls/result
+        # pairs are never split across the recent/older divide.
+        if len(other_msgs) > self.preserve_recent:
+            recent_cut = self._snap_to_pair_boundary(
+                other_msgs, len(other_msgs) - self.preserve_recent
+            )
+        else:
+            recent_cut = 0
+        recent = other_msgs[recent_cut:]
        
        # Determine what to summarize based on iterative settings
        total_original_messages = len(messages)
@@ -786,13 +896,14 @@ class ContextCompactor:
            messages_since_summary = total_original_messages - self._previous_summary_global_idx
            new_older_messages = max(0, messages_since_summary - self.preserve_recent)
            if new_older_messages > 0:
-                older = other_msgs[-messages_since_summary:-self.preserve_recent]
+                older = other_msgs[-messages_since_summary:recent_cut]
            else:
                older = []
            self._used_previous_summary = True
        else:
-            # Fresh summary: summarize all older messages
-            older = other_msgs[:-self.preserve_recent] if len(other_msgs) > self.preserve_recent else []
+            # Fresh summary: summarize all older messages (kept in sync with the
+            # snapped recent boundary so a tool pair is never split)
+            older = other_msgs[:recent_cut]
            self._used_previous_summary = False
        
        if older and self.llm_summarize_fn:
@@ -0,0 +1,135 @@
+"""Read-only session recap built on the existing summariser.
+
+The compaction machinery in this package normally runs to *shrink* context.
+``build_recap`` reuses that same summariser purely to *inform* the user: it
+renders a short "where were we" block from a transcript **without mutating the
+conversation or triggering compaction**. This is the shared core primitive
+behind the ``/recap`` bot command and ``praisonai session show --recap``.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List
+
+RECAP_HEADER = "Recap — where we were:"
+
+# A recap is a *glanceable* re-entry aid, not a full transcript. Bound the
+# rendered block so a large persisted/compaction summary can never produce an
+# output that overflows a delivery channel (e.g. Telegram's 4096-char message
+# limit) or scrolls a terminal. Kept comfortably under that ceiling so channel
+# framing/markdown never tips it over.
+RECAP_MAX_CHARS = 3500
+
+
+def _persisted_summary(history: List[Dict[str, Any]]) -> str:
+    """Return an already-distilled summary embedded in the transcript, if any.
+
+    Prefers the most recent compaction checkpoint (a system message tagged
+    ``_compacted``) or the naive ``[Previous conversation summary]`` line, so a
+    recap can start cheaply from what the model already carries (Issue #3062).
+    """
+    found = ""
+    for msg in history:
+        content = msg.get("content")
+        if msg.get("_compacted") and isinstance(content, str):
+            found = content
+        elif (
+            msg.get("role") == "system"
+            and isinstance(content, str)
+            and content.startswith("[Previous conversation summary]")
+        ):
+            found = content
+    return found
+
+
+def _naive_summary(history: List[Dict[str, Any]]) -> str:
+    """Distil older turns with the compactor's offline summarise pass.
+
+    Operates on a shallow copy so the caller's transcript is never modified and
+    no compaction event is emitted. Returns ``""`` on any failure so recap can
+    never crash a chat.
+    """
+    try:
+        from .compactor import ContextCompactor
+        from .strategy import CompactionStrategy
+
+        compactor = ContextCompactor(strategy=CompactionStrategy.SUMMARIZE)
+        summarised = compactor._summarize([dict(m) for m in history])
+        for msg in summarised:
+            content = msg.get("content")
+            if (
+                msg.get("role") == "system"
+                and isinstance(content, str)
+                and content.startswith("[Previous conversation summary]")
+            ):
+                return content
+    except Exception:  # noqa: BLE001 - recap must never raise
+        return ""
+    return ""
+
+
+def build_recap(
+    history: List[Dict[str, Any]],
+    tail: int = 4,
+    max_chars: int = RECAP_MAX_CHARS,
+) -> str:
+    """Render a read-only "where were we" summary of a transcript.
+
+    Reuses the existing summariser (a persisted compaction summary when one is
+    embedded, otherwise the naive summarise pass) and always tops up with the
+    most recent ``tail`` messages so the recap reflects the latest activity.
+    The input ``history`` is never modified and no compaction is triggered.
+
+    The rendered block is bounded to ``max_chars`` so a large persisted summary
+    can never overflow a delivery channel (e.g. Telegram's 4096-char message
+    limit) or flood a terminal; the recent tail is always preserved and the
+    (older) summary is what gets trimmed, keeping the most relevant context.
+
+    Args:
+        history: The conversation messages (not modified).
+        tail: How many recent messages to append verbatim.
+        max_chars: Upper bound on the rendered recap length. ``0`` or negative
+            disables the cap.
+
+    Returns:
+        A short, human-readable recap block, or a "nothing yet" note.
+    """
+    if not history:
+        return "Nothing to recap yet — this session has no messages."
+
+    summary_text = _persisted_summary(history) or _naive_summary(history)
+
+    tail_lines: List[str] = []
+    for msg in history[-tail:] if tail > 0 else []:
+        role = msg.get("role", "?")
+        content = msg.get("content", "")
+        if isinstance(content, str) and content.strip():
+            snippet = content.strip().replace("\n", " ")
+            if len(snippet) > 160:
+                snippet = snippet[:160] + "…"
+            tail_lines.append(f"• {role}: {snippet}")
+
+    header = f"📌 {RECAP_HEADER}"
+
+    if max_chars and max_chars > 0 and summary_text:
+        # Reserve room for the header, the recent tail, and joining newlines so
+        # the *most recent* activity is never dropped in favour of the older
+        # summary. Only the summary is trimmed to fit the budget.
+        tail_block = ""
+        if tail_lines:
+            tail_block = "\n".join(["Recent:", *tail_lines])
+        # +2 accounts for the newlines that will join header/summary/tail.
+        reserved = len(header) + len(tail_block) + 2
+        budget = max_chars - reserved
+        if budget <= 0:
+            summary_text = ""
+        elif len(summary_text) > budget:
+            summary_text = summary_text[: max(0, budget - 1)].rstrip() + "…"
+
+    parts: List[str] = [header]
+    if summary_text:
+        parts.append(summary_text)
+    if tail_lines:
+        parts.append("Recent:")
+        parts.extend(tail_lines)
+    return "\n".join(parts)
@@ -8,7 +8,6 @@ The implementation is extracted from workflows.py _evaluate_condition()
 to enable DRY condition handling across the codebase.
 """
 import re
-import logging
 from praisonaiagents._logging import get_logger
 from typing import Dict, Any, List, Optional

@@ -778,6 +778,9 @@ class ExecutionConfig:
    max_steps: Optional[int] = None
    
    # Rate limiting
+    # When set (positive int) and ``rate_limiter`` is omitted, the Agent
+    # auto-creates ``RateLimiter(requests_per_minute=max_rpm)``. Provide
+    # ``rate_limiter`` explicitly for burst/TPM control (it takes precedence).
    max_rpm: Optional[int] = None
    
    # Time limits
@@ -950,7 +953,16 @@ class ExecutionConfig:
        if isinstance(context_compaction, dict):
            from ..context.policy import ContextCompactionPolicy
            context_compaction = ContextCompactionPolicy.from_dict(context_compaction)
-        
+
+        # Handle compaction_strategy restoration (serialised as a string value in to_dict)
+        compaction_strategy = data.get("compaction_strategy")
+        if isinstance(compaction_strategy, str):
+            from ..compaction.strategy import CompactionStrategy
+            try:
+                compaction_strategy = CompactionStrategy(compaction_strategy)
+            except ValueError:
+                compaction_strategy = None
+
        return cls(
            max_iter=data.get("max_iter", 20),
            max_steps=data.get("max_steps", None),
@@ -958,13 +970,17 @@ class ExecutionConfig:
            max_rpm=data.get("max_rpm", None),
            max_execution_time=data.get("max_execution_time", None),
            max_retry_limit=data.get("max_retry_limit", 2),
+            retry_initial_delay=data.get("retry_initial_delay", 1.0),
+            retry_backoff_factor=data.get("retry_backoff_factor", 2.0),
+            retry_jitter=data.get("retry_jitter", 0.1),
            code_execution=data.get("code_execution", False),
            code_mode=data.get("code_mode", "safe"),
-            code_sandbox_mode=data.get("code_sandbox_mode", "docker"),
+            code_sandbox_mode=data.get("code_sandbox_mode", "sandbox"),
            code_tools=data.get("code_tools", False),
            code_tools_allow=data.get("code_tools_allow", None),
            context_compaction=context_compaction,
            max_context_tokens=data.get("max_context_tokens", None),
+            compaction_strategy=compaction_strategy,
            max_budget=data.get("max_budget", None),
            parallel_tool_calls=data.get("parallel_tool_calls", False),
        )
@@ -1076,7 +1092,13 @@ class ToolConfig:
    artifact_retention_days: int = 7  # Days to retain artifacts before garbage collection
    artifact_store: Optional[Any] = None  # Custom artifact store instance
    redact_secrets: bool = True  # Whether to redact secrets from artifacts
-    
+
+    # Allow resolving tool calls via the process-global @tool registry when a
+    # tool name is not in this agent's declared tools=[...]. Default False so an
+    # agent is scoped strictly to its own tools (safe by default); opt in for
+    # plugin-host style dynamic dispatch.
+    allow_global_tools: bool = False
+
    def __post_init__(self) -> None:
        """Validate configuration after initialization."""
        if self.output_limit <= 0:
@@ -1105,6 +1127,7 @@ class ToolConfig:
            "artifact_retention_days": self.artifact_retention_days,
            "artifact_store": self.artifact_store,
            "redact_secrets": self.redact_secrets,
+            "allow_global_tools": self.allow_global_tools,
        }
    
    @classmethod
@@ -1130,6 +1153,7 @@ class ToolConfig:
            artifact_retention_days=data.get("artifact_retention_days", 7),
            artifact_store=data.get("artifact_store"),
            redact_secrets=data.get("redact_secrets", True),
+            allow_global_tools=data.get("allow_global_tools", False),
        )


@@ -41,6 +41,7 @@ VALID_PLUGINS_KEYS = {
    "enabled": (bool, list, str),  # bool, list of plugin names, or "true"/"false"
    "auto_discover": (bool,),
    "directories": (list,),
+    "allow_project_plugins": (bool,),  # opt-in trust gate for ./.praisonai/plugins/*.py
 }

 VALID_DEFAULTS_KEYS = {
@@ -110,6 +111,10 @@ class PluginsConfig:
    """Configuration for the plugin system."""
    enabled: Union[bool, List[str]] = False  # True, False, or list of plugin names
    auto_discover: bool = True
+    # Opt-in trust gate for executing project-local single-file plugins
+    # (./.praisonai/plugins/*.py). Default False so a cloned repo cannot run
+    # arbitrary plugin code until the user explicitly authorises it.
+    allow_project_plugins: bool = False
    directories: List[str] = field(default_factory=lambda: [
        str(_default_project_plugins_dir()),
        str(_default_global_plugins_dir())
@@ -124,6 +129,7 @@ class PluginsConfig:
        result = {
            "enabled": self.enabled,
            "auto_discover": self.auto_discover,
+            "allow_project_plugins": self.allow_project_plugins,
            "directories": self.directories,
        }
        # Flatten per-plugin option maps back to top level for round-tripping.
@@ -315,7 +321,7 @@ def _dict_to_plugins_config(data: Dict[str, Any]) -> PluginsConfig:
    system; any other key whose value is a mapping is treated as a per-plugin
    option map delivered to that plugin's ``on_config`` hook.
    """
-    reserved = {"enabled", "auto_discover", "directories"}
+    reserved = {"enabled", "auto_discover", "directories", "allow_project_plugins"}
    options = {
        name: value
        for name, value in data.items()
@@ -324,6 +330,7 @@ def _dict_to_plugins_config(data: Dict[str, Any]) -> PluginsConfig:
    return PluginsConfig(
        enabled=data.get("enabled", False),
        auto_discover=data.get("auto_discover", True),
+        allow_project_plugins=data.get("allow_project_plugins", False),
        directories=data.get("directories", [
            str(_default_project_plugins_dir()),
            str(_default_global_plugins_dir())
@@ -583,6 +590,113 @@ def get_plugin_options() -> Dict[str, Dict[str, Any]]:
    return dict(get_plugins_config().options)


+def _config_write_target() -> Path:
+    """Resolve the config file the CLI should write plugin enable/disable to.
+
+    Returns the existing config file if one is already present (so the CLI
+    mutates the *same* file the runtime reads), otherwise the project-local
+    ``.praisonai/config.yaml`` — the unified surface — as the default target.
+    This closes the config split-brain where the CLI wrote a JSON file the
+    runtime never read.
+    """
+    existing = _find_config_file()
+    if existing is not None:
+        return existing
+    return get_project_data_dir() / "config.yaml"
+
+
+def _dump_config_file(path: Path, data: Dict[str, Any]) -> None:
+    """Write ``data`` to ``path`` as YAML or TOML based on its suffix."""
+    path.parent.mkdir(parents=True, exist_ok=True)
+    if path.suffix.lower() in (".yaml", ".yml"):
+        import yaml
+
+        with open(path, "w", encoding="utf-8") as f:
+            yaml.safe_dump(data, f, sort_keys=False, default_flow_style=False)
+    else:
+        try:
+            import tomli_w
+        except ImportError:
+            # Do NOT write a YAML sidecar: the runtime keeps reading the
+            # original .toml (higher precedence), so the write would be
+            # silently lost and re-introduce the config split-brain. Fail
+            # fast with a remediation hint instead.
+            raise RuntimeError(
+                f"Cannot write TOML config {path}: no TOML writer available. "
+                "Install tomli-w (pip install tomli-w), or convert the config "
+                "to .praisonai/config.yaml."
+            ) from None
+        with open(path, "wb") as f:
+            tomli_w.dump(data, f)
+
+
+def set_plugin_enabled(name: str, enabled: bool) -> Path:
+    """Persist a plugin's enabled state to the config the runtime reads.
+
+    Mutates the ``plugins.enabled`` allow-list in the project's config file
+    (the same file ``get_enabled_plugins`` reads), creating
+    ``.praisonai/config.yaml`` if no config exists yet. This is the single
+    source of truth the CLI and runtime share — no separate JSON file.
+
+    Args:
+        name: Plugin name to enable/disable.
+        enabled: True to add to the allow-list, False to remove it.
+
+    Returns:
+        The path of the config file that was written.
+    """
+    target = _config_write_target()
+    raw = _load_config() if _find_config_file() is not None else {}
+    if not isinstance(raw, dict):
+        raw = {}
+
+    plugins = raw.get("plugins")
+    if not isinstance(plugins, dict):
+        plugins = {}
+        raw["plugins"] = plugins
+
+    has_enabled_key = "enabled" in plugins
+    current = plugins.get("enabled")
+    # Normalise the enabled flag into a list of names we can mutate.
+    if isinstance(current, list):
+        names = [str(n) for n in current]
+    elif isinstance(current, str) and current.strip():
+        names = [current.strip()]
+    elif current is True:
+        # Explicit "all plugins enabled" mode. Collapsing this to an allow-list
+        # would silently disable every other plugin, so we only touch this
+        # state when the requested change is well-defined:
+        #   - enable: already enabled, no-op (leave "all enabled" intact)
+        #   - disable: cannot be expressed as an allow-list without naming the
+        #     full set, so refuse rather than disable everything.
+        if enabled:
+            clear_config_cache()
+            return target
+        raise ValueError(
+            f"Cannot disable '{name}': plugins.enabled is currently set to "
+            "'all' (true). Set plugins.enabled to an explicit list of plugin "
+            "names first, then disable individual plugins."
+        )
+    elif current is None and not has_enabled_key:
+        # No allow-list configured yet (fresh config): start an empty list so
+        # the first enable produces [name] and the first disable is a no-op.
+        names = []
+    else:
+        # Falsy explicit value (e.g. enabled: false) — start from empty.
+        names = []
+
+    if enabled:
+        if name not in names:
+            names.append(name)
+    else:
+        names = [n for n in names if n != name]
+
+    plugins["enabled"] = names
+    _dump_config_file(target, raw)
+    clear_config_cache()
+    return target
+
+
 def _defaults_has_any_values() -> bool:
    """Return True if config file defines any defaults (cached after first check)."""
    global _defaults_has_values
@@ -50,42 +50,6 @@ def detect_url_scheme(value: str) -> Optional[str]:
    return None


-def parse_url_to_config(
-    url: str,
-    config_class: type,
-    url_schemes: Dict[str, str],
-) -> Any:
-    """
-    Parse a URL string into a config object.
-    
-    Args:
-        url: URL string (e.g., "postgresql://localhost/db")
-        config_class: Config dataclass to instantiate
-        url_schemes: Mapping of URL schemes to backend names
-        
-    Returns:
-        Config instance with backend and url set
-        
-    Raises:
-        ValueError: If URL scheme is not supported
-    """
-    scheme = detect_url_scheme(url)
-    if not scheme:
-        raise ValueError(f"Invalid URL format: {url}")
-    
-    if scheme not in url_schemes:
-        valid_schemes = ", ".join(sorted(url_schemes.keys()))
-        raise ValueError(
-            f"Unsupported URL scheme '{scheme}' in '{url}'. "
-            f"Supported schemes: {valid_schemes}"
-        )
-    
-    backend = url_schemes[scheme]
-    
-    # Create config with backend and URL in config dict
-    return config_class(backend=backend, config={"url": url})
-
-
 def is_path_like(value: str) -> bool:
    """
    Check if a string looks like a file path. O(1) operation.
@@ -136,21 +100,6 @@ def is_path_like(value: str) -> bool:
    return False


-def is_numeric_string(value: str) -> bool:
-    """
-    Check if a string is numeric. O(1) operation.
-    
-    Args:
-        value: String to check
-        
-    Returns:
-        True if string is numeric
-    """
-    if not isinstance(value, str):
-        return False
-    return value.isdigit()
-
-
 def suggest_similar(value: str, candidates: Iterable[str], max_distance: int = 2) -> Optional[str]:
    """
    Find the most similar string from candidates using Levenshtein distance.
@@ -246,28 +195,6 @@ def make_preset_error(
    return ValueError(" ".join(msg_parts))


-def make_array_error(
-    param_name: str,
-    value: list,
-    expected_format: str,
-) -> ValueError:
-    """
-    Create a helpful error message for invalid array format.
-    
-    Args:
-        param_name: Name of the parameter
-        value: Invalid array value
-        expected_format: Description of expected format
-        
-    Returns:
-        ValueError with helpful message
-    """
-    return ValueError(
-        f"Invalid {param_name} array format: {value}. "
-        f"Expected: {expected_format}"
-    )
-
-
 def is_policy_string(value: str) -> bool:
    """
    Check if a string is a policy specification. O(1) operation.
@@ -6,7 +6,6 @@ Inspired by CrewAI's ContextualMemory pattern.
 """

 import asyncio
-import logging
 from praisonaiagents._logging import get_logger
 from dataclasses import dataclass, field
 from typing import Any, Callable, Dict, List, Optional, Tuple, Union
@@ -60,16 +60,54 @@ OUTPUT_RESERVES: Dict[str, int] = {
 }


+def _litellm_model_info(model: str) -> Optional[Dict[str, Any]]:
+    """
+    Look up a model's info from litellm's ``model_cost`` registry.
+
+    Lazy-imported so there is zero overhead (and no hard dependency) when
+    litellm is not installed. Returns ``None`` when litellm is absent or the
+    model is unknown.
+    """
+    try:
+        from litellm import model_cost
+    except Exception:
+        return None
+
+    try:
+        model_lower = model.lower()
+        if model_lower in model_cost:
+            return model_cost[model_lower]
+        # Try with provider prefix removed (e.g. "openai/gpt-4o" -> "gpt-4o")
+        if "/" in model:
+            base_model = model.split("/")[-1].lower()
+            if base_model in model_cost:
+                return model_cost[base_model]
+    except Exception:
+        return None
+    return None
+
+
 def get_model_limit(model: str) -> int:
    """
    Get context window limit for a model.
-    
+
+    Resolves against litellm's ``model_cost`` registry first (``max_input_tokens``),
+    so any model the underlying LLM layer knows gets the correct window — then
+    falls back to the static ``MODEL_LIMITS`` table for offline use.
+
    Args:
        model: Model name or identifier
-        
+
    Returns:
        Context window size in tokens
    """
+    # Prefer data-driven lookup via litellm (context window = max_input_tokens)
+    info = _litellm_model_info(model)
+    if info:
+        limit = info.get("max_input_tokens") or info.get("max_tokens")
+        if limit:
+            return limit
+
    # Exact match
    if model in MODEL_LIMITS:
        return MODEL_LIMITS[model]
@@ -86,13 +124,24 @@ def get_model_limit(model: str) -> int:
 def get_output_reserve(model: str) -> int:
    """
    Get recommended output token reserve for a model.
-    
+
+    Resolves against litellm's ``model_cost`` registry first
+    (``max_output_tokens``), then falls back to the static ``OUTPUT_RESERVES``
+    table for offline use.
+
    Args:
        model: Model name
-        
+
    Returns:
        Output reserve in tokens
    """
+    # Prefer data-driven lookup via litellm (output reserve = max_output_tokens)
+    info = _litellm_model_info(model)
+    if info:
+        reserve = info.get("max_output_tokens")
+        if reserve:
+            return reserve
+
    model_lower = model.lower()
    
    for key, reserve in OUTPUT_RESERVES.items():
@@ -12,7 +12,6 @@ Design principles:
 """

 import asyncio
-import logging
 from praisonaiagents._logging import get_logger
 from typing import Optional, List

@@ -12,7 +12,6 @@ Design principles:
 - Preserves most relevant content
 """

-import logging
 from praisonaiagents._logging import get_logger
 from typing import Protocol, Optional, List
 from dataclasses import dataclass
@@ -7,7 +7,6 @@ Injects FastContext results into the main agent with:
 - Precision over recall (avoid context pollution)
 """

-import logging
 from praisonaiagents._logging import get_logger
 from typing import Optional, List, Dict, Any
 from dataclasses import dataclass
@@ -25,7 +25,6 @@ Example usage:
 import os
 import hashlib
 import json
-import logging
 from praisonaiagents._logging import get_logger
 from typing import Optional, List, Dict, Any

@@ -10,7 +10,6 @@ This agent is designed for fast context retrieval using:

 import os
 import json
-import logging
 from praisonaiagents._logging import get_logger
 from typing import List, Dict, Any, Optional

@@ -15,7 +15,6 @@ Design principles:
 import os
 import json
 import hashlib
-import logging
 from praisonaiagents._logging import get_logger
 from dataclasses import dataclass, field, asdict
 from pathlib import Path
@@ -12,7 +12,6 @@ import os
 import fnmatch
 import hashlib
 import json
-import logging
 from praisonaiagents._logging import get_logger
 from dataclasses import dataclass
 from typing import Dict, List, Set, Optional, Any
@@ -1,318 +0,0 @@
-"""
-File Watcher for Incremental Indexing.
-
-Monitors file system changes and triggers incremental index updates:
- Watches for file creation, modification, deletion
- Debounces rapid changes
- Supports background indexing
-"""
-
-import os
-import time
-import logging
-from praisonaiagents._logging import get_logger
-import threading
-from typing import Dict, Set, Callable, Optional, Any
-from dataclasses import dataclass
-from enum import Enum
-
-logger = get_logger(__name__)
-
-class ChangeType(Enum):
-    """Types of file system changes."""
-    CREATED = "created"
-    MODIFIED = "modified"
-    DELETED = "deleted"
-
-@dataclass
-class FileChange:
-    """Represents a file system change.
-    
-    Attributes:
-        path: Path to the changed file
-        change_type: Type of change
-        timestamp: When the change was detected
-    """
-    path: str
-    change_type: ChangeType
-    timestamp: float
-
-class FileWatcher:
-    """Watches for file system changes and triggers callbacks.
-    
-    Uses polling-based approach for cross-platform compatibility.
-    For production use, consider using watchdog library.
-    
-    Attributes:
-        workspace_path: Root directory to watch
-        extensions: File extensions to watch
-        poll_interval: Seconds between polls
-    """
-    
-    def __init__(
-        self,
-        workspace_path: str,
-        extensions: Optional[Set[str]] = None,
-        poll_interval: float = 1.0,
-        debounce_delay: float = 0.5,
-        on_change: Optional[Callable[[FileChange], None]] = None
-    ):
-        """Initialize file watcher.
-        
-        Args:
-            workspace_path: Root directory to watch
-            extensions: File extensions to watch (None = all)
-            poll_interval: Seconds between polls
-            debounce_delay: Delay before processing changes
-            on_change: Callback for file changes
-        """
-        self.workspace_path = os.path.abspath(workspace_path)
-        self.extensions = extensions or {
-            '.py', '.js', '.ts', '.jsx', '.tsx', '.go', '.rs', '.java',
-            '.c', '.cpp', '.h', '.hpp', '.cs', '.rb', '.php', '.swift'
-        }
-        self.poll_interval = poll_interval
-        self.debounce_delay = debounce_delay
-        self.on_change = on_change
-        
-        # State tracking
-        self._file_mtimes: Dict[str, float] = {}
-        self._pending_changes: Dict[str, FileChange] = {}
-        self._running = False
-        self._thread: Optional[threading.Thread] = None
-        self._lock = threading.Lock()
-    
-    def _scan_files(self) -> Dict[str, float]:
-        """Scan workspace and get file modification times.
-        
-        Returns:
-            Dict mapping file paths to modification times
-        """
-        mtimes = {}
-        
-        for root, dirs, files in os.walk(self.workspace_path):
-            # Skip hidden directories
-            dirs[:] = [d for d in dirs if not d.startswith('.')]
-            
-            for filename in files:
-                ext = os.path.splitext(filename)[1].lower()
-                if ext in self.extensions:
-                    file_path = os.path.join(root, filename)
-                    try:
-                        mtimes[file_path] = os.path.getmtime(file_path)
-                    except OSError:
-                        pass
-        
-        return mtimes
-    
-    def _detect_changes(self, new_mtimes: Dict[str, float]) -> None:
-        """Detect changes between old and new file states.
-        
-        Args:
-            new_mtimes: New file modification times
-        """
-        old_paths = set(self._file_mtimes.keys())
-        new_paths = set(new_mtimes.keys())
-        
-        now = time.time()
-        
-        # Detect created files
-        for path in new_paths - old_paths:
-            self._add_pending_change(FileChange(
-                path=path,
-                change_type=ChangeType.CREATED,
-                timestamp=now
-            ))
-        
-        # Detect deleted files
-        for path in old_paths - new_paths:
-            self._add_pending_change(FileChange(
-                path=path,
-                change_type=ChangeType.DELETED,
-                timestamp=now
-            ))
-        
-        # Detect modified files
-        for path in old_paths & new_paths:
-            if new_mtimes[path] > self._file_mtimes[path]:
-                self._add_pending_change(FileChange(
-                    path=path,
-                    change_type=ChangeType.MODIFIED,
-                    timestamp=now
-                ))
-        
-        self._file_mtimes = new_mtimes
-    
-    def _add_pending_change(self, change: FileChange) -> None:
-        """Add a change to pending queue (with debouncing).
-        
-        Args:
-            change: File change to add
-        """
-        with self._lock:
-            self._pending_changes[change.path] = change
-    
-    def _process_pending_changes(self) -> None:
-        """Process pending changes after debounce delay."""
-        with self._lock:
-            now = time.time()
-            to_process = []
-            
-            for path, change in list(self._pending_changes.items()):
-                if now - change.timestamp >= self.debounce_delay:
-                    to_process.append(change)
-                    del self._pending_changes[path]
-        
-        # Process changes outside lock
-        for change in to_process:
-            if self.on_change:
-                try:
-                    self.on_change(change)
-                except Exception as e:
-                    logger.error(f"Error processing change {change.path}: {e}")
-    
-    def _poll_loop(self) -> None:
-        """Main polling loop."""
-        # Initial scan
-        self._file_mtimes = self._scan_files()
-        
-        while self._running:
-            try:
-                # Scan for changes
-                new_mtimes = self._scan_files()
-                self._detect_changes(new_mtimes)
-                
-                # Process pending changes
-                self._process_pending_changes()
-                
-            except Exception as e:
-                logger.error(f"Error in file watcher: {e}")
-            
-            time.sleep(self.poll_interval)
-    
-    def start(self) -> None:
-        """Start watching for file changes."""
-        if self._running:
-            return
-        
-        self._running = True
-        self._thread = threading.Thread(target=self._poll_loop, daemon=True)
-        self._thread.start()
-        logger.info(f"File watcher started for {self.workspace_path}")
-    
-    def stop(self) -> None:
-        """Stop watching for file changes."""
-        self._running = False
-        if self._thread:
-            self._thread.join(timeout=2.0)
-            self._thread = None
-        logger.info("File watcher stopped")
-    
-    def __enter__(self):
-        self.start()
-        return self
-    
-    def __exit__(self, exc_type, exc_val, exc_tb):
-        self.stop()
-
-class IncrementalIndexer:
-    """Manages incremental index updates based on file changes.
-    
-    Combines FileIndexer/SymbolIndexer with FileWatcher for
-    automatic index updates when files change.
-    """
-    
-    def __init__(
-        self,
-        workspace_path: str,
-        file_indexer: Optional[Any] = None,
-        symbol_indexer: Optional[Any] = None,
-        poll_interval: float = 2.0
-    ):
-        """Initialize incremental indexer.
-        
-        Args:
-            workspace_path: Root directory to index
-            file_indexer: FileIndexer instance (optional)
-            symbol_indexer: SymbolIndexer instance (optional)
-            poll_interval: Seconds between file system polls
-        """
-        self.workspace_path = os.path.abspath(workspace_path)
-        self.file_indexer = file_indexer
-        self.symbol_indexer = symbol_indexer
-        
-        self._watcher = FileWatcher(
-            workspace_path=workspace_path,
-            poll_interval=poll_interval,
-            on_change=self._handle_change
-        )
-        
-        # Statistics
-        self.changes_processed = 0
-        self.last_change_time: Optional[float] = None
-    
-    def _handle_change(self, change: FileChange) -> None:
-        """Handle a file change.
-        
-        Args:
-            change: File change to process
-        """
-        rel_path = os.path.relpath(change.path, self.workspace_path)
-        logger.debug(f"Processing {change.change_type.value}: {rel_path}")
-        
-        if change.change_type == ChangeType.DELETED:
-            # Remove from indexes
-            if self.file_indexer and hasattr(self.file_indexer, 'files'):
-                self.file_indexer.files.pop(rel_path, None)
-            if self.symbol_indexer and hasattr(self.symbol_indexer, 'symbols'):
-                self.symbol_indexer.symbols.pop(rel_path, None)
-        else:
-            # Re-index the file
-            if self.file_indexer and hasattr(self.file_indexer, 'index_file'):
-                # FileIndexer doesn't have index_file, so we skip
-                pass
-            if self.symbol_indexer and hasattr(self.symbol_indexer, 'index_file'):
-                self.symbol_indexer.index_file(change.path)
-        
-        self.changes_processed += 1
-        self.last_change_time = time.time()
-    
-    def start(self) -> None:
-        """Start incremental indexing."""
-        # Initial full index
-        if self.file_indexer:
-            self.file_indexer.index()
-        if self.symbol_indexer:
-            self.symbol_indexer.index()
-        
-        # Start watching
-        self._watcher.start()
-    
-    def stop(self) -> None:
-        """Stop incremental indexing."""
-        self._watcher.stop()
-    
-    def get_stats(self) -> Dict[str, Any]:
-        """Get indexer statistics.
-        
-        Returns:
-            Dictionary with stats
-        """
-        stats = {
-            "changes_processed": self.changes_processed,
-            "last_change_time": self.last_change_time
-        }
-        
-        if self.file_indexer:
-            stats["file_indexer"] = self.file_indexer.get_stats()
-        if self.symbol_indexer:
-            stats["symbol_indexer"] = self.symbol_indexer.get_stats()
-        
-        return stats
-    
-    def __enter__(self):
-        self.start()
-        return self
-    
-    def __exit__(self, exc_type, exc_val, exc_tb):
-        self.stop()
@@ -11,7 +11,6 @@ Extracts code symbols from source files:

 import os
 import re
-import logging
 from praisonaiagents._logging import get_logger
 from dataclasses import dataclass, field
 from typing import Dict, List, Set, Optional, Any
@@ -11,7 +11,6 @@ Provides async parallel execution of search tools with:
 import asyncio
 from concurrent.futures import ThreadPoolExecutor
 from typing import List, Dict, Any, Optional, Callable
-import logging
 from praisonaiagents._logging import get_logger
 import time

@@ -11,7 +11,6 @@ Design principles:
 - No performance impact on default behavior
 """

-import logging
 from praisonaiagents._logging import get_logger
 from typing import Protocol, List, Dict, Any, Optional, runtime_checkable

@@ -1,366 +0,0 @@
-"""
-Search Strategy for Fast Context.
-
-Orchestrates multi-turn search with:
- Turn 1-3: Exploration (grep, glob, directory listing)
- Turn 4: Final answer (file list + line ranges)
- Early termination if sufficient context found
-"""
-
-import logging
-from praisonaiagents._logging import get_logger
-from dataclasses import dataclass, field
-from typing import List, Dict, Any, Optional, Set
-from enum import Enum
-
-from praisonaiagents.context.fast.result import FastContextResult, FileMatch, LineRange
-from praisonaiagents.context.fast.parallel_executor import ToolCallBatch
-
-logger = get_logger(__name__)
-
-class SearchPhase(Enum):
-    """Phases of the search strategy."""
-    DISCOVERY = "discovery"      # Turn 1: Discover structure
-    EXPLORATION = "exploration"  # Turn 2-3: Deep search
-    REFINEMENT = "refinement"    # Turn 4: Final answer
-
-@dataclass
-class SearchState:
-    """Tracks the state of a multi-turn search.
-    
-    Attributes:
-        query: Original search query
-        current_turn: Current turn number (1-indexed)
-        max_turns: Maximum turns allowed
-        phase: Current search phase
-        discovered_files: Files found so far
-        explored_paths: Paths already explored
-        result: Accumulated search result
-        should_terminate: Whether to terminate early
-    """
-    query: str
-    current_turn: int = 0
-    max_turns: int = 4
-    phase: SearchPhase = SearchPhase.DISCOVERY
-    discovered_files: Set[str] = field(default_factory=set)
-    explored_paths: Set[str] = field(default_factory=set)
-    result: FastContextResult = field(default_factory=FastContextResult)
-    should_terminate: bool = False
-    
-    # Thresholds for early termination
-    min_files_for_termination: int = 5
-    max_files_before_refinement: int = 20
-    
-    def advance_turn(self) -> None:
-        """Advance to the next turn and update phase."""
-        self.current_turn += 1
-        
-        if self.current_turn == 1:
-            self.phase = SearchPhase.DISCOVERY
-        elif self.current_turn < self.max_turns:
-            self.phase = SearchPhase.EXPLORATION
-        else:
-            self.phase = SearchPhase.REFINEMENT
-    
-    def check_early_termination(self) -> bool:
-        """Check if search should terminate early.
-        
-        Returns:
-            True if search should terminate
-        """
-        # Terminate if we have enough high-quality results
-        if len(self.discovered_files) >= self.min_files_for_termination:
-            high_relevance = sum(
-                1 for f in self.result.files 
-                if f.relevance_score >= 0.8
-            )
-            if high_relevance >= 3:
-                self.should_terminate = True
-                return True
-        
-        # Terminate if we've explored everything
-        if self.current_turn >= 2 and not self._has_unexplored_paths():
-            self.should_terminate = True
-            return True
-        
-        return False
-    
-    def _has_unexplored_paths(self) -> bool:
-        """Check if there are unexplored paths."""
-        # Simple heuristic: if we found files but haven't explored many paths
-        return len(self.discovered_files) > len(self.explored_paths) * 2
-
-class SearchStrategy:
-    """Orchestrates multi-turn search strategy.
-    
-    Implements the Fast Context search approach:
-    - Turn 1: Discovery - understand codebase structure
-    - Turn 2-3: Exploration - deep search for relevant code
-    - Turn 4: Refinement - finalize results
-    
-    Supports early termination when sufficient context is found.
-    """
-    
-    def __init__(
-        self,
-        workspace_path: str,
-        max_turns: int = 4,
-        max_parallel: int = 8
-    ):
-        """Initialize search strategy.
-        
-        Args:
-            workspace_path: Root directory for searches
-            max_turns: Maximum search turns
-            max_parallel: Maximum parallel tool calls per turn
-        """
-        self.workspace_path = workspace_path
-        self.max_turns = max_turns
-        self.max_parallel = max_parallel
-    
-    def create_state(self, query: str) -> SearchState:
-        """Create a new search state.
-        
-        Args:
-            query: Search query
-            
-        Returns:
-            New SearchState instance
-        """
-        state = SearchState(query=query, max_turns=self.max_turns)
-        state.result.query = query
-        return state
-    
-    def plan_discovery_turn(self, state: SearchState) -> ToolCallBatch:
-        """Plan the discovery turn (Turn 1).
-        
-        Focus on understanding codebase structure:
-        - List root directory
-        - Find common file patterns
-        - Initial grep for query terms
-        
-        Args:
-            state: Current search state
-            
-        Returns:
-            Batch of tool calls to execute
-        """
-        batch = ToolCallBatch(max_size=self.max_parallel)
-        query = state.query
-        
-        # List root directory
-        batch.add("list_directory", dir_path=self.workspace_path, recursive=False)
-        
-        # Find Python files (most common)
-        batch.add("glob_search", search_path=self.workspace_path, pattern="**/*.py", max_results=20)
-        
-        # Initial grep for query terms
-        query_words = query.lower().split()
-        for word in query_words[:3]:  # First 3 words
-            if len(word) >= 3:  # Skip short words
-                batch.add("grep_search", search_path=self.workspace_path, pattern=word, max_results=10)
-                if batch.is_full:
-                    break
-        
-        return batch
-    
-    def plan_exploration_turn(self, state: SearchState) -> ToolCallBatch:
-        """Plan an exploration turn (Turn 2-3).
-        
-        Deep search based on discovery results:
-        - Search in discovered directories
-        - Read promising files
-        - Follow references
-        
-        Args:
-            state: Current search state
-            
-        Returns:
-            Batch of tool calls to execute
-        """
-        batch = ToolCallBatch(max_size=self.max_parallel)
-        
-        # Read top files found so far
-        for file_match in state.result.files[:4]:
-            if file_match.path not in state.explored_paths:
-                batch.add("read_file", filepath=file_match.path, context_lines=5)
-                state.explored_paths.add(file_match.path)
-                if batch.is_full:
-                    break
-        
-        # Search in unexplored directories
-        unexplored_dirs = self._find_unexplored_dirs(state)
-        for dir_path in unexplored_dirs[:2]:
-            batch.add("list_directory", dir_path=dir_path, recursive=True, max_depth=2)
-            if batch.is_full:
-                break
-        
-        # Additional grep searches with refined patterns
-        if not batch.is_full:
-            refined_patterns = self._generate_refined_patterns(state)
-            for pattern in refined_patterns[:2]:
-                batch.add("grep_search", search_path=self.workspace_path, pattern=pattern, max_results=15)
-                if batch.is_full:
-                    break
-        
-        return batch
-    
-    def plan_refinement_turn(self, state: SearchState) -> ToolCallBatch:
-        """Plan the refinement turn (Turn 4).
-        
-        Finalize results:
-        - Read remaining important files
-        - Get specific line ranges
-        
-        Args:
-            state: Current search state
-            
-        Returns:
-            Batch of tool calls to execute
-        """
-        batch = ToolCallBatch(max_size=self.max_parallel)
-        
-        # Read top files that haven't been fully explored
-        for file_match in state.result.files[:self.max_parallel]:
-            if file_match.path not in state.explored_paths:
-                # Read specific line ranges if available
-                if file_match.line_ranges:
-                    for lr in file_match.line_ranges[:2]:
-                        batch.add(
-                            "read_file",
-                            filepath=file_match.path,
-                            start_line=max(1, lr.start - 5),
-                            end_line=lr.end + 5
-                        )
-                        if batch.is_full:
-                            break
-                else:
-                    batch.add("read_file", filepath=file_match.path)
-                
-                state.explored_paths.add(file_match.path)
-                if batch.is_full:
-                    break
-        
-        return batch
-    
-    def plan_next_turn(self, state: SearchState) -> Optional[ToolCallBatch]:
-        """Plan the next turn based on current state.
-        
-        Args:
-            state: Current search state
-            
-        Returns:
-            Batch of tool calls, or None if search should end
-        """
-        state.advance_turn()
-        
-        # Check for early termination
-        if state.should_terminate or state.current_turn > state.max_turns:
-            return None
-        
-        if state.check_early_termination():
-            return None
-        
-        # Plan based on phase
-        if state.phase == SearchPhase.DISCOVERY:
-            return self.plan_discovery_turn(state)
-        elif state.phase == SearchPhase.EXPLORATION:
-            return self.plan_exploration_turn(state)
-        else:  # REFINEMENT
-            return self.plan_refinement_turn(state)
-    
-    def process_results(
-        self,
-        state: SearchState,
-        tool_results: List[Any]
-    ) -> None:
-        """Process results from a turn and update state.
-        
-        Args:
-            state: Current search state
-            tool_results: Results from tool execution
-        """
-        for result in tool_results:
-            if isinstance(result, list):
-                # Grep or glob results
-                for item in result:
-                    if isinstance(item, dict):
-                        path = item.get("path", "")
-                        if path:
-                            state.discovered_files.add(path)
-                            
-                            # Create or update file match
-                            file_match = FileMatch(
-                                path=path,
-                                relevance_score=0.8,
-                                match_count=1
-                            )
-                            
-                            # Add line range if available
-                            line_num = item.get("line_number")
-                            if line_num:
-                                file_match.add_line_range(LineRange(
-                                    start=max(1, line_num - 2),
-                                    end=line_num + 2,
-                                    content=item.get("context"),
-                                    relevance_score=0.8
-                                ))
-                            
-                            state.result.add_file(file_match)
-            
-            elif isinstance(result, dict):
-                # Read file or list directory result
-                if result.get("success"):
-                    path = result.get("path", "")
-                    if path:
-                        state.explored_paths.add(path)
-                    
-                    # Handle directory listing
-                    entries = result.get("entries", [])
-                    for entry in entries:
-                        if not entry.get("is_dir"):
-                            state.discovered_files.add(entry.get("path", ""))
-    
-    def _find_unexplored_dirs(self, state: SearchState) -> List[str]:
-        """Find directories that haven't been explored.
-        
-        Args:
-            state: Current search state
-            
-        Returns:
-            List of unexplored directory paths
-        """
-        import os
-        
-        # Extract unique directories from discovered files
-        dirs = set()
-        for file_path in state.discovered_files:
-            dir_path = os.path.dirname(file_path)
-            if dir_path and dir_path not in state.explored_paths:
-                dirs.add(dir_path)
-        
-        return list(dirs)[:5]  # Limit to 5
-    
-    def _generate_refined_patterns(self, state: SearchState) -> List[str]:
-        """Generate refined search patterns based on results.
-        
-        Args:
-            state: Current search state
-            
-        Returns:
-            List of refined search patterns
-        """
-        patterns = []
-        query_words = state.query.lower().split()
-        
-        # Combine query words
-        if len(query_words) >= 2:
-            patterns.append(f"{query_words[0]}.*{query_words[1]}")
-        
-        # Add common code patterns
-        for word in query_words[:2]:
-            if len(word) >= 3:
-                patterns.append(f"def {word}")
-                patterns.append(f"class {word}")
-        
-        return patterns[:4]
@@ -15,7 +15,6 @@ import re
 import fnmatch
 from pathlib import Path
 from typing import List, Dict, Any, Optional, Set
-import logging
 from praisonaiagents._logging import get_logger

 logger = get_logger(__name__)
@@ -9,7 +9,6 @@ from dataclasses import dataclass, field, asdict
 from typing import Any, Dict, List, Optional
 from datetime import datetime, timezone
 import json
-import logging
 from praisonaiagents._logging import get_logger

 logger = get_logger(__name__)
@@ -18,7 +18,6 @@ Zero Performance Impact:

 import threading
 import json
-import logging
 from praisonaiagents._logging import get_logger
 from typing import Dict, List, Any, Optional
 from dataclasses import dataclass
@@ -10,7 +10,6 @@ from typing import Any, Dict, List, Optional
 from enum import Enum
 import time
 import hashlib
-import logging
 from praisonaiagents._logging import get_logger

 logger = get_logger(__name__)
@@ -5,7 +5,6 @@ Provides lightweight tracing and metrics collection for escalation execution.
 Opt-in only - no overhead when not enabled.
 """

-import logging
 from praisonaiagents._logging import get_logger
 import time
 from dataclasses import dataclass, field
@@ -4,7 +4,6 @@ Escalation Pipeline for PraisonAI Agents.
 Implements progressive escalation from direct response to full autonomous mode.
 """

-import logging
 from praisonaiagents._logging import get_logger
 import time
 from typing import Any, Dict, List, Optional, Callable
@@ -107,6 +107,12 @@ __all__ = [
    # PromptOptimizer (optimise agent.instructions against an eval, keep best)
    "PromptOptimizer",
    "OptimizeResult",
+    # Trials engine (K isolated attempts per case, pass-rate + frontier)
+    "run_trials",
+    "arun_trials",
+    "TrialScore",
+    "TrialAttempt",
+    "TrialReport",
 ]

 _LAZY_IMPORTS = {
@@ -191,6 +197,12 @@ _LAZY_IMPORTS = {
    # PromptOptimizer (optimise agent.instructions against an eval, keep best)
    "PromptOptimizer": ("prompt_optimizer", "PromptOptimizer"),
    "OptimizeResult": ("prompt_optimizer", "OptimizeResult"),
+    # Trials engine (K isolated attempts per case, pass-rate + frontier)
+    "run_trials": ("trials", "run_trials"),
+    "arun_trials": ("trials", "arun_trials"),
+    "TrialScore": ("trials", "TrialScore"),
+    "TrialAttempt": ("trials", "TrialAttempt"),
+    "TrialReport": ("trials", "TrialReport"),
 }


@@ -5,7 +5,6 @@ Evaluates agent output accuracy by comparing against expected output using LLM-a
 """

 import os
-import logging
 from praisonaiagents._logging import get_logger
 from typing import Callable, Optional, Union, TYPE_CHECKING

@@ -7,7 +7,6 @@ This module provides the abstract base class that all evaluators inherit from.
 from abc import ABC, abstractmethod
 from typing import Any, Dict, Optional, Union, TYPE_CHECKING
 import uuid
-import logging
 from praisonaiagents._logging import get_logger

 if TYPE_CHECKING:
@@ -5,7 +5,6 @@ Evaluates agent outputs against custom criteria using LLM-as-judge.
 """

 import os
-import logging
 from praisonaiagents._logging import get_logger
 from typing import Callable, Literal, Optional, Union, TYPE_CHECKING