Add [1.8.1] changelog compare link and update [Unreleased] base

* Fix Magentic to share agent replies across team

The per-round instruction was sent untargeted (fan-out delivered it to
every participant) and replies were never relayed, so a later speaker saw
the prior speaker's instruction but not its response - inverted from
GroupChatHost and the Python reference.

- Target the instruction at the selected speaker only.
- Broadcast each reply to the other participants (buffered, no TurnToken),
  excluding the responder via _currentSpeakerExecutorId, mirroring
  GroupChatHost.
- Persist _currentSpeakerExecutorId across checkpoints.
- Add a regression test.

* Address review feedback: null-guard, explicit checkpoint key, drop vacuous assertion

* Address review feedback: centralize checkpoint keys, clear current speaker

- Move CurrentSpeakerStateKey into MagenticConstants as
  nameof(CurrentSpeakerStateKey)
- Clear _currentSpeakerExecutorId in ResetAndReplanAsync and
  PrepareFinalAnswerAsync so a checkpoint taken in those windows does not
  persist a stale speaker
- Add UTF-8 BOM to RecordingEchoAgent.cs to satisfy the format check.

docs/assets/SVG/Microsoft Foundry Agent Framework - Color.svg

@@ -0,0 +1,55 @@
+<svg width="256" height="256" viewBox="0 0 256 256" fill="none" xmlns="http://www.w3.org/2000/svg">
+<rect width="256" height="256" transform="matrix(-1 0 0 1 256 0)" fill="white"/>
+<path d="M163.006 36.0262C155.129 31.4785 145.424 31.4759 137.533 36.0284L104.002 55.3877C107.838 53.2763 112.07 52.2274 116.296 52.2248C120.633 52.2231 124.976 53.3247 128.871 55.5411L174.091 81.6479C175.11 82.2362 175.738 83.3236 175.738 84.5004V151.263C175.738 152.716 177.313 153.621 178.568 152.895L196.967 142.28C204.845 137.732 209.704 129.326 209.704 120.221V77.7299C209.704 68.6342 204.855 60.227 196.967 55.6697L190.983 52.2141C190.65 52.0008 190.313 51.7921 189.969 51.5933L163.006 36.0262Z" fill="url(#paint0_linear_481_4810)"/>
+<path d="M163.006 36.0262C155.129 31.4785 145.424 31.4759 137.533 36.0284L104.002 55.3877C107.838 53.2763 112.07 52.2274 116.296 52.2248C120.633 52.2231 124.976 53.3247 128.871 55.5411L174.091 81.6479C175.11 82.2362 175.738 83.3236 175.738 84.5004V151.263C175.738 152.716 177.313 153.621 178.568 152.895L196.967 142.28C204.845 137.732 209.704 129.326 209.704 120.221V77.7299C209.704 68.6342 204.855 60.227 196.967 55.6697L190.983 52.2141C190.65 52.0008 190.313 51.7921 189.969 51.5933L163.006 36.0262Z" fill="url(#paint1_linear_481_4810)"/>
+<path d="M103.548 55.6397L103.557 55.6451L104.002 55.3877C103.851 55.471 103.698 55.5531 103.548 55.6397Z" fill="url(#paint2_linear_481_4810)"/>
+<path d="M103.548 55.6397L103.557 55.6451L104.002 55.3877C103.851 55.471 103.698 55.5531 103.548 55.6397Z" fill="url(#paint3_linear_481_4810)"/>
+<path d="M116.308 52.2209C111.903 52.2271 107.507 53.3498 103.561 55.6366C95.6702 60.1891 90.8239 68.6019 90.8231 77.6986L90.8223 167.846C90.8222 169.786 92.871 171.041 94.599 170.16L103.523 165.611C116.573 158.959 124.788 145.549 124.788 130.902V62.9894C124.778 58.6476 129.49 55.9209 133.25 58.0698L128.879 55.5453C124.976 53.3242 120.645 52.2192 116.308 52.2209Z" fill="url(#paint4_linear_481_4810)"/>
+<path d="M95.3068 221.682C103.184 226.23 112.889 226.232 120.78 221.68L154.311 202.32C150.475 204.432 146.243 205.481 142.018 205.483C137.68 205.485 133.337 204.383 129.442 202.167L84.2226 176.06C83.2035 175.472 82.5757 174.384 82.5757 173.208L82.5757 106.445C82.5757 104.992 81 104.087 79.7451 104.813L61.3465 115.428C53.4682 119.976 48.6091 128.382 48.6089 137.487L48.6089 179.978C48.6089 189.074 53.4585 197.481 61.3465 202.038L67.3303 205.494C67.6629 205.707 68.0002 205.916 68.3446 206.115L95.3068 221.682Z" fill="url(#paint5_linear_481_4810)"/>
+<path d="M95.3068 221.682C103.184 226.23 112.889 226.232 120.78 221.68L154.311 202.32C150.475 204.432 146.243 205.481 142.018 205.483C137.68 205.485 133.337 204.383 129.442 202.167L84.2226 176.06C83.2035 175.472 82.5757 174.384 82.5757 173.208L82.5757 106.445C82.5757 104.992 81 104.087 79.7451 104.813L61.3465 115.428C53.4682 119.976 48.6091 128.382 48.6089 137.487L48.6089 179.978C48.6089 189.074 53.4585 197.481 61.3465 202.038L67.3303 205.494C67.6629 205.707 68.0002 205.916 68.3446 206.115L95.3068 221.682Z" fill="url(#paint6_linear_481_4810)"/>
+<path d="M154.765 202.068L154.756 202.063L154.311 202.32C154.463 202.237 154.615 202.155 154.765 202.068Z" fill="url(#paint7_linear_481_4810)"/>
+<path d="M154.765 202.068L154.756 202.063L154.311 202.32C154.463 202.237 154.615 202.155 154.765 202.068Z" fill="url(#paint8_linear_481_4810)"/>
+<path d="M142.003 205.487C146.408 205.481 150.805 204.358 154.751 202.071C162.641 197.519 167.488 189.106 167.488 180.009L167.489 89.8618C167.489 87.9222 165.44 86.667 163.712 87.5479L154.788 92.0972C141.739 98.7494 133.523 112.159 133.523 126.806L133.523 194.719C133.533 199.06 128.821 201.787 125.061 199.638L129.432 202.163C133.336 204.384 137.666 205.489 142.003 205.487Z" fill="url(#paint9_linear_481_4810)"/>
+<defs>
+<linearGradient id="paint0_linear_481_4810" x1="207.413" y1="61.882" x2="148.999" y2="163.067" gradientUnits="userSpaceOnUse">
+<stop stop-color="#9189F7"/>
+<stop offset="1" stop-color="#4135E9"/>
+</linearGradient>
+<linearGradient id="paint1_linear_481_4810" x1="188.235" y1="204.189" x2="264.21" y2="152.592" gradientUnits="userSpaceOnUse">
+<stop stop-color="#4F42FD"/>
+<stop offset="1" stop-color="#7274FF"/>
+</linearGradient>
+<linearGradient id="paint2_linear_481_4810" x1="207.413" y1="61.882" x2="148.999" y2="163.067" gradientUnits="userSpaceOnUse">
+<stop stop-color="#9189F7"/>
+<stop offset="1" stop-color="#4135E9"/>
+</linearGradient>
+<linearGradient id="paint3_linear_481_4810" x1="188.235" y1="204.189" x2="264.21" y2="152.592" gradientUnits="userSpaceOnUse">
+<stop stop-color="#4F42FD"/>
+<stop offset="1" stop-color="#7274FF"/>
+</linearGradient>
+<linearGradient id="paint4_linear_481_4810" x1="93.1761" y1="128.826" x2="66.2399" y2="104.746" gradientUnits="userSpaceOnUse">
+<stop offset="0.25" stop-color="#4F42FD"/>
+<stop offset="1" stop-color="#2C08AC"/>
+</linearGradient>
+<linearGradient id="paint5_linear_481_4810" x1="50.9004" y1="195.826" x2="109.315" y2="94.6412" gradientUnits="userSpaceOnUse">
+<stop stop-color="#9189F7"/>
+<stop offset="1" stop-color="#4135E9"/>
+</linearGradient>
+<linearGradient id="paint6_linear_481_4810" x1="70.0787" y1="53.5188" x2="-5.89657" y2="105.116" gradientUnits="userSpaceOnUse">
+<stop stop-color="#4F42FD"/>
+<stop offset="1" stop-color="#7274FF"/>
+</linearGradient>
+<linearGradient id="paint7_linear_481_4810" x1="50.9004" y1="195.826" x2="109.315" y2="94.6412" gradientUnits="userSpaceOnUse">
+<stop stop-color="#9189F7"/>
+<stop offset="1" stop-color="#4135E9"/>
+</linearGradient>
+<linearGradient id="paint8_linear_481_4810" x1="70.0787" y1="53.5188" x2="-5.89657" y2="105.116" gradientUnits="userSpaceOnUse">
+<stop stop-color="#4F42FD"/>
+<stop offset="1" stop-color="#7274FF"/>
+</linearGradient>
+<linearGradient id="paint9_linear_481_4810" x1="165.135" y1="128.882" x2="192.072" y2="152.962" gradientUnits="userSpaceOnUse">
+<stop offset="0.25" stop-color="#4F42FD"/>
+<stop offset="1" stop-color="#2C08AC"/>
+</linearGradient>
+</defs>
+</svg>

docs/assets/SVG/Microsoft Foundry Agent Framework - Fill (Black).svg

@@ -0,0 +1,5 @@
+<svg width="256" height="256" viewBox="0 0 256 256" fill="none" xmlns="http://www.w3.org/2000/svg">
+<rect width="256" height="256" transform="matrix(-1 0 0 1 256 0)" fill="white"/>
+<path d="M167.489 89.8618C167.489 87.9224 165.441 86.667 163.713 87.5473L154.788 92.0971C141.739 98.7493 133.523 112.159 133.523 126.806V194.718C133.533 199.053 128.837 201.777 125.08 199.647L84.2227 176.06C83.2036 175.472 82.5762 174.384 82.5762 173.207V106.445C82.5759 104.992 80.9999 104.087 79.7451 104.813L61.3467 115.428C53.4685 119.976 48.6096 128.382 48.6094 137.487V179.978C48.6094 189.074 53.4588 197.481 61.3467 202.039L67.3301 205.494C67.6627 205.707 68.0004 205.916 68.3447 206.115L95.3066 221.682C103.184 226.23 112.889 226.232 120.779 221.679L154.312 202.32C154.271 202.342 154.23 202.362 154.189 202.384C154.283 202.333 154.375 202.281 154.468 202.229L154.312 202.32C154.463 202.237 154.615 202.154 154.765 202.068L154.762 202.065C162.646 197.511 167.487 189.102 167.488 180.009L167.489 89.8618Z" fill="black"/>
+<path d="M163.007 36.0259C155.13 31.4781 145.424 31.4763 137.533 36.0288L104.002 55.3882C104.029 55.3732 104.057 55.359 104.084 55.3442C104.02 55.3794 103.956 55.4159 103.893 55.4516L104.002 55.3882C103.851 55.4714 103.699 55.5536 103.549 55.6401L103.552 55.6411C95.6664 60.1948 90.8241 68.6053 90.8232 77.6987L90.8223 167.846C90.8223 169.786 92.8707 171.04 94.5986 170.16L103.523 165.611C116.573 158.959 124.788 145.549 124.788 130.902V62.9897C124.778 58.6479 129.49 55.9211 133.25 58.0698L174.091 81.6479C175.11 82.2363 175.737 83.3238 175.737 84.5005V151.263C175.738 152.716 177.314 153.621 178.568 152.895L196.967 142.28C204.845 137.732 209.704 129.326 209.704 120.221V77.73C209.704 68.6343 204.855 60.2267 196.967 55.6694L190.982 52.2143C190.65 52.0011 190.313 51.792 189.969 51.5932L163.007 36.0259Z" fill="black"/>
+</svg>

docs/assets/SVG/Microsoft Foundry Agent Framework - Fill (White).svg

@@ -0,0 +1,5 @@
+<svg width="256" height="256" viewBox="0 0 256 256" fill="none" xmlns="http://www.w3.org/2000/svg">
+<rect width="256" height="256" transform="matrix(-1 0 0 1 256 0)" fill="black"/>
+<path d="M167.489 89.8618C167.489 87.9224 165.441 86.667 163.713 87.5473L154.788 92.0971C141.739 98.7493 133.523 112.159 133.523 126.806V194.718C133.533 199.053 128.837 201.777 125.08 199.647L84.2227 176.06C83.2036 175.472 82.5762 174.384 82.5762 173.207V106.445C82.5759 104.992 80.9999 104.087 79.7451 104.813L61.3467 115.428C53.4685 119.976 48.6096 128.382 48.6094 137.487V179.978C48.6094 189.074 53.4588 197.481 61.3467 202.039L67.3301 205.494C67.6627 205.707 68.0004 205.916 68.3447 206.115L95.3066 221.682C103.184 226.23 112.889 226.232 120.779 221.679L154.312 202.32C154.271 202.342 154.23 202.362 154.189 202.384C154.283 202.333 154.375 202.281 154.468 202.229L154.312 202.32C154.463 202.237 154.615 202.154 154.765 202.068L154.762 202.065C162.646 197.511 167.487 189.102 167.488 180.009L167.489 89.8618Z" fill="white"/>
+<path d="M163.007 36.0259C155.13 31.4781 145.424 31.4763 137.533 36.0288L104.002 55.3882C104.029 55.3732 104.057 55.359 104.084 55.3442C104.02 55.3794 103.956 55.4159 103.893 55.4516L104.002 55.3882C103.851 55.4714 103.699 55.5536 103.549 55.6401L103.552 55.6411C95.6664 60.1948 90.8241 68.6053 90.8232 77.6987L90.8223 167.846C90.8223 169.786 92.8707 171.04 94.5986 170.16L103.523 165.611C116.573 158.959 124.788 145.549 124.788 130.902V62.9897C124.778 58.6479 129.49 55.9211 133.25 58.0698L174.091 81.6479C175.11 82.2363 175.737 83.3238 175.737 84.5005V151.263C175.738 152.716 177.314 153.621 178.568 152.895L196.967 142.28C204.845 137.732 209.704 129.326 209.704 120.221V77.73C209.704 68.6343 204.855 60.2267 196.967 55.6694L190.982 52.2143C190.65 52.0011 190.313 51.792 189.969 51.5932L163.007 36.0259Z" fill="white"/>
+</svg>

docs/assets/SVG/Microsoft Foundry Agent Framework - Stroke (Black).svg

@@ -0,0 +1,4 @@
+<svg width="256" height="256" viewBox="0 0 256 256" fill="none" xmlns="http://www.w3.org/2000/svg">
+<rect width="256" height="256" transform="matrix(-1 0 0 1 256 0)" fill="white"/>
+<path d="M48.6094 179.978V137.487C48.6096 128.382 53.4685 119.976 61.3467 115.428L79.7451 104.813C80.9999 104.087 82.5759 104.992 82.5762 106.445V173.207C82.5762 174.384 83.2036 175.472 84.2227 176.06L125.08 199.647C128.837 201.777 133.533 199.053 133.523 194.718V126.806C133.523 112.388 141.484 99.1684 154.18 92.4135L154.788 92.0971L163.713 87.5473C165.441 86.667 167.489 87.9224 167.489 89.8618L167.488 180.009L167.474 180.86C167.181 189.624 162.399 197.653 154.762 202.065L154.765 202.068C154.615 202.154 154.463 202.237 154.312 202.32L154.468 202.229C154.375 202.281 154.283 202.333 154.189 202.384C154.23 202.362 154.271 202.342 154.312 202.32L120.779 221.679L120.034 222.092C112.534 226.093 103.539 226.092 96.0508 222.095L95.3066 221.682L68.3447 206.115C68.0004 205.916 67.6627 205.707 67.3301 205.494L61.3467 202.039C53.7053 197.624 48.9149 189.595 48.623 180.829L48.6094 179.978ZM175.737 84.5005C175.737 83.3974 175.186 82.3728 174.277 81.7641L174.091 81.6479L133.25 58.0698C129.49 55.9211 124.778 58.6479 124.788 62.9897V130.902L124.782 131.587C124.53 145.966 116.369 159.063 103.523 165.611L94.5986 170.16L94.4355 170.236C92.799 170.938 90.9459 169.803 90.8281 168.026L90.8223 167.846L90.8232 77.6987C90.8241 68.6053 95.6664 60.1948 103.552 55.6411L103.549 55.6401C103.699 55.5536 103.851 55.4714 104.002 55.3882L103.893 55.4516C103.956 55.4159 104.02 55.3794 104.084 55.3442C104.057 55.359 104.029 55.3732 104.002 55.3882L137.533 36.0288C145.424 31.4763 155.13 31.4781 163.007 36.0259L189.969 51.5932C190.313 51.792 190.65 52.0011 190.982 52.2143L196.967 55.6694C204.855 60.2267 209.704 68.6343 209.704 77.73V120.221L209.689 121.073C209.397 129.848 204.599 137.874 196.967 142.28L178.568 152.895C177.314 153.621 175.738 152.716 175.737 151.263V84.5005ZM176.814 149.866L176.819 149.864L176.832 149.856C176.826 149.859 176.82 149.862 176.814 149.866ZM137.023 194.71L137.019 195.038C136.802 201.878 129.341 206.087 123.354 202.692L123.33 202.678L82.4727 179.091C80.3698 177.877 79.0762 175.634 79.0762 173.207V109.239L63.0957 118.458C56.5124 122.259 52.3745 129.183 52.1221 136.752L52.1094 137.487V179.978C52.1094 187.823 56.2909 195.075 63.0957 199.007H63.0967L69.0801 202.462L69.1504 202.503L69.2188 202.547C69.5212 202.741 69.8111 202.92 70.0947 203.083L97.0566 218.651L97.6982 219.007C104.372 222.569 112.434 222.453 119.029 218.648L152.514 199.316L152.512 199.312C152.581 199.274 152.65 199.236 152.752 199.178L152.753 199.181C152.775 199.169 152.796 199.158 152.815 199.147L153.011 199.035C159.81 195.107 163.987 187.854 163.988 180.009V91.3344L156.378 95.2153C144.501 101.27 137.023 113.475 137.023 126.806V194.71ZM94.3223 166.372L101.934 162.493C113.811 156.438 121.288 144.233 121.288 130.902V62.9897C121.278 55.9521 128.901 51.5532 134.986 55.0307L135 55.0385L175.841 78.6167L176.036 78.7339C178.023 79.9714 179.237 82.15 179.237 84.5005V148.468L195.217 139.249C202.013 135.326 206.204 128.075 206.204 120.221V77.73C206.204 69.8848 202.022 62.6318 195.217 58.6997L189.232 55.2456L189.162 55.2046L189.094 55.1606C188.788 54.9649 188.5 54.787 188.219 54.6245L161.257 39.0571C154.463 35.135 146.091 35.1311 139.282 39.0591L139.283 39.06L105.765 58.4106L105.767 58.4135C105.713 58.443 105.723 58.4383 105.602 58.5063L105.6 58.5034C105.535 58.5391 105.481 58.5691 105.433 58.5962L105.302 58.6723C98.5016 62.5995 94.324 69.8532 94.3232 77.6987L94.3223 166.372Z" fill="black"/>
+</svg>

docs/assets/SVG/Microsoft Foundry Agent Framework - Stroke (White).svg

@@ -0,0 +1,4 @@
+<svg width="256" height="256" viewBox="0 0 256 256" fill="none" xmlns="http://www.w3.org/2000/svg">
+<rect width="256" height="256" transform="matrix(-1 0 0 1 256 0)" fill="black"/>
+<path d="M48.6094 179.978V137.487C48.6096 128.382 53.4685 119.976 61.3467 115.428L79.7451 104.813C80.9999 104.087 82.5759 104.992 82.5762 106.445V173.207C82.5762 174.384 83.2036 175.472 84.2227 176.06L125.08 199.647C128.837 201.777 133.533 199.053 133.523 194.718V126.806C133.523 112.388 141.484 99.1684 154.18 92.4135L154.788 92.0971L163.713 87.5473C165.441 86.667 167.489 87.9224 167.489 89.8618L167.488 180.009L167.474 180.86C167.181 189.624 162.399 197.653 154.762 202.065L154.765 202.068C154.615 202.154 154.463 202.237 154.312 202.32L154.468 202.229C154.375 202.281 154.283 202.333 154.189 202.384C154.23 202.362 154.271 202.342 154.312 202.32L120.779 221.679L120.034 222.092C112.534 226.093 103.539 226.092 96.0508 222.095L95.3066 221.682L68.3447 206.115C68.0004 205.916 67.6627 205.707 67.3301 205.494L61.3467 202.039C53.7053 197.624 48.9149 189.595 48.623 180.829L48.6094 179.978ZM175.737 84.5005C175.737 83.3974 175.186 82.3728 174.277 81.7641L174.091 81.6479L133.25 58.0698C129.49 55.9211 124.778 58.6479 124.788 62.9897V130.902L124.782 131.587C124.53 145.966 116.369 159.063 103.523 165.611L94.5986 170.16L94.4355 170.236C92.799 170.938 90.9459 169.803 90.8281 168.026L90.8223 167.846L90.8232 77.6987C90.8241 68.6053 95.6664 60.1948 103.552 55.6411L103.549 55.6401C103.699 55.5536 103.851 55.4714 104.002 55.3882L103.893 55.4516C103.956 55.4159 104.02 55.3794 104.084 55.3442C104.057 55.359 104.029 55.3732 104.002 55.3882L137.533 36.0288C145.424 31.4763 155.13 31.4781 163.007 36.0259L189.969 51.5932C190.313 51.792 190.65 52.0011 190.982 52.2143L196.967 55.6694C204.855 60.2267 209.704 68.6343 209.704 77.73V120.221L209.689 121.073C209.397 129.848 204.599 137.874 196.967 142.28L178.568 152.895C177.314 153.621 175.738 152.716 175.737 151.263V84.5005ZM176.814 149.866L176.819 149.864L176.832 149.856C176.826 149.859 176.82 149.862 176.814 149.866ZM137.023 194.71L137.019 195.038C136.802 201.878 129.341 206.087 123.354 202.692L123.33 202.678L82.4727 179.091C80.3698 177.877 79.0762 175.634 79.0762 173.207V109.239L63.0957 118.458C56.5124 122.259 52.3745 129.183 52.1221 136.752L52.1094 137.487V179.978C52.1094 187.823 56.2909 195.075 63.0957 199.007H63.0967L69.0801 202.462L69.1504 202.503L69.2188 202.547C69.5212 202.741 69.8111 202.92 70.0947 203.083L97.0566 218.651L97.6982 219.007C104.372 222.569 112.434 222.453 119.029 218.648L152.514 199.316L152.512 199.312C152.581 199.274 152.65 199.236 152.752 199.178L152.753 199.181C152.775 199.169 152.796 199.158 152.815 199.147L153.011 199.035C159.81 195.107 163.987 187.854 163.988 180.009V91.3344L156.378 95.2153C144.501 101.27 137.023 113.475 137.023 126.806V194.71ZM94.3223 166.372L101.934 162.493C113.811 156.438 121.288 144.233 121.288 130.902V62.9897C121.278 55.9521 128.901 51.5532 134.986 55.0307L135 55.0385L175.841 78.6167L176.036 78.7339C178.023 79.9714 179.237 82.15 179.237 84.5005V148.468L195.217 139.249C202.013 135.326 206.204 128.075 206.204 120.221V77.73C206.204 69.8848 202.022 62.6318 195.217 58.6997L189.232 55.2456L189.162 55.2046L189.094 55.1606C188.788 54.9649 188.5 54.787 188.219 54.6245L161.257 39.0571C154.463 35.135 146.091 35.1311 139.282 39.0591L139.283 39.06L105.765 58.4106L105.767 58.4135C105.713 58.443 105.723 58.4383 105.602 58.5063L105.6 58.5034C105.535 58.5391 105.481 58.5691 105.433 58.5962L105.302 58.6723C98.5016 62.5995 94.324 69.8532 94.3232 77.6987L94.3223 166.372Z" fill="white"/>
+</svg>

dotnet/Directory.Packages.props

@@ -99,7 +99,7 @@
     <PackageVersion Include="Microsoft.SemanticKernel.Connectors.InMemory" Version="1.67.0-preview" />
     <PackageVersion Include="Microsoft.SemanticKernel.Connectors.Qdrant" Version="1.67.0-preview" />
     <!-- Agent SDKs -->
-    <PackageVersion Include="GitHub.Copilot.SDK" Version="1.0.0-beta.2" />
+    <PackageVersion Include="GitHub.Copilot.SDK" Version="1.0.0" />
     <PackageVersion Include="Microsoft.Agents.CopilotStudio.Client" Version="1.3.171-beta" />
     <!-- M365 Agents SDK -->
     <PackageVersion Include="AdaptiveCards" Version="3.1.0" />

dotnet/samples/02-agents/AgentProviders/Agent_With_GitHubCopilot/Agent_With_GitHubCopilot.csproj

@@ -6,6 +6,7 @@
 
     <Nullable>enable</Nullable>
     <ImplicitUsings>enable</ImplicitUsings>
+    <NoWarn>$(NoWarn);GHCP001</NoWarn>
   </PropertyGroup>
 
   <ItemGroup>

dotnet/samples/02-agents/AgentProviders/Agent_With_GitHubCopilot/Program.cs

@@ -2,21 +2,22 @@
 
 // This sample shows how to create a GitHub Copilot agent with shell command permissions.
 
-using GitHub.Copilot.SDK;
+using GitHub.Copilot;
+using GitHub.Copilot.Rpc;
 using Microsoft.Agents.AI;
 
 // Permission handler that prompts the user for approval
-static Task<PermissionRequestResult> PromptPermission(PermissionRequest request, PermissionInvocation invocation)
+static Task<PermissionDecision> PromptPermission(PermissionRequest request, PermissionInvocation invocation)
 {
     Console.WriteLine($"\n[Permission Request: {request.Kind}]");
     Console.Write("Approve? (y/n): ");
 
     string? input = Console.ReadLine()?.Trim().ToUpperInvariant();
-    PermissionRequestResultKind kind = input is "Y" or "YES"
-                                     ? PermissionRequestResultKind.Approved
-                                     : PermissionRequestResultKind.Rejected;
+    PermissionDecision decision = input is "Y" or "YES"
+                                     ? PermissionDecision.ApproveOnce()
+                                     : PermissionDecision.Reject();
 
-    return Task.FromResult(new PermissionRequestResult { Kind = kind });
+    return Task.FromResult(decision);
 }
 
 // Create and start a Copilot client

dotnet/samples/02-agents/AgentProviders/Agent_With_GitHubCopilot/README.md

@@ -36,7 +36,7 @@ dotnet run
 You can customize the agent by providing additional configuration:
 
 ```csharp
-using GitHub.Copilot.SDK;
+using GitHub.Copilot;
 using Microsoft.Agents.AI;
 
 // Create and start a Copilot client

dotnet/samples/02-agents/Harness/Harness_Step01_Research/Program.cs

@@ -79,8 +79,10 @@ AIAgent agent =
     .GetProjectOpenAIClient()
     .GetResponsesClient()
     .AsIChatClient(deploymentName)
-    .AsHarnessAgent(MaxContextWindowTokens, MaxOutputTokens, new HarnessAgentOptions
+    .AsHarnessAgent(new HarnessAgentOptions
     {
+        MaxContextWindowTokens = MaxContextWindowTokens,
+        MaxOutputTokens = MaxOutputTokens,
         Name = "ResearchAgent",
         Description = "A research assistant that plans and executes research tasks.",
         DisableFileAccess = true,                           // If enabled, this would allow the agent to read/write files in a working directory

dotnet/samples/02-agents/Harness/Harness_Step02_Research_WithBackgroundAgents/Program.cs

@@ -44,8 +44,10 @@ AIAgent webSearchAgent =
     .GetProjectOpenAIClient()
     .GetResponsesClient()
     .AsIChatClient(deploymentName)
-    .AsHarnessAgent(MaxContextWindowTokens, MaxOutputTokens, new HarnessAgentOptions
+    .AsHarnessAgent(new HarnessAgentOptions
     {
+        MaxContextWindowTokens = MaxContextWindowTokens,
+        MaxOutputTokens = MaxOutputTokens,
         Name = "WebSearchAgent",
         Description = "An agent that can search the web to find information.",
         OpenTelemetrySourceName = TracingSourceName,
@@ -92,8 +94,10 @@ AIAgent parentAgent =
     .GetProjectOpenAIClient()
     .GetResponsesClient()
     .AsIChatClient(deploymentName)
-    .AsHarnessAgent(MaxContextWindowTokens, MaxOutputTokens, new HarnessAgentOptions
+    .AsHarnessAgent(new HarnessAgentOptions
     {
+        MaxContextWindowTokens = MaxContextWindowTokens,
+        MaxOutputTokens = MaxOutputTokens,
         Name = "StockPriceResearcher",
         Description = "An agent that researches stock prices using background agents.",
         OpenTelemetrySourceName = TracingSourceName,

dotnet/samples/02-agents/Harness/Harness_Step03_DataProcessing/Program.cs

@@ -68,8 +68,10 @@ AIAgent agent =
     .GetProjectOpenAIClient()
     .GetResponsesClient()
     .AsIChatClient(deploymentName)
-    .AsHarnessAgent(MaxContextWindowTokens, MaxOutputTokens, new HarnessAgentOptions
+    .AsHarnessAgent(new HarnessAgentOptions
     {
+        MaxContextWindowTokens = MaxContextWindowTokens,
+        MaxOutputTokens = MaxOutputTokens,
         Name = "DataAnalyst",
         Description = "A data analyst assistant that reads, analyzes, and processes data files.",
         OpenTelemetrySourceName = TracingSourceName,

dotnet/samples/02-agents/Harness/Harness_Step04_CodeExecution/Program.cs

@@ -89,8 +89,10 @@ AIAgent agent =
     .GetProjectOpenAIClient()
     .GetResponsesClient()
     .AsIChatClient(deploymentName)
-    .AsHarnessAgent(MaxContextWindowTokens, MaxOutputTokens, new HarnessAgentOptions
+    .AsHarnessAgent(new HarnessAgentOptions
     {
+        MaxContextWindowTokens = MaxContextWindowTokens,
+        MaxOutputTokens = MaxOutputTokens,
         Name = "CodeExecutionAgent",
         Description = "A technical assistant with sandboxed code execution and skill-based workflows.",
         OpenTelemetrySourceName = TracingSourceName,

dotnet/src/Microsoft.Agents.AI.Foundry.Hosting/HostedFoundryMemoryProviderScopes.cs

@@ -44,18 +44,33 @@ public static class HostedFoundryMemoryProviderScopes
         session => new FoundryMemoryProvider.State(new FoundryMemoryProviderScope(GetRequiredHostedContext(session).ChatId));
 
     /// <summary>
-    /// Returns a <c>stateInitializer</c> that scopes memories per (user, chat) pair, using
-    /// <c>"{UserId}:{ChatId}"</c> as the partition key. Use this when memories should be visible
-    /// only to the same user within the same conversation.
+    /// Returns a <c>stateInitializer</c> that scopes memories per (user, chat) pair, composing
+    /// <see cref="HostedSessionContext.UserId"/> and <see cref="HostedSessionContext.ChatId"/> into a
+    /// single delimiter-safe partition key. Use this when memories should be visible only to the same
+    /// user within the same conversation.
     /// </summary>
+    /// <remarks>
+    /// Both identity values are opaque strings that may contain any characters, including the <c>:</c>
+    /// delimiter. To keep the composite key injective (so two distinct (user, chat) pairs can never
+    /// collide), each part is escaped (<c>\</c> becomes <c>\\</c>, then <c>:</c> becomes <c>\:</c>) before
+    /// being joined with a <c>::</c> separator.
+    /// </remarks>
     /// <returns>A delegate suitable for the <c>stateInitializer</c> argument of <see cref="FoundryMemoryProvider"/>.</returns>
     public static Func<AgentSession?, FoundryMemoryProvider.State> PerUserAndChat() =>
         session =>
         {
             var ctx = GetRequiredHostedContext(session);
-            return new FoundryMemoryProvider.State(new FoundryMemoryProviderScope($"{ctx.UserId}:{ctx.ChatId}"));
+            return new FoundryMemoryProvider.State(
+                new FoundryMemoryProviderScope($"{EscapeScopePart(ctx.UserId)}::{EscapeScopePart(ctx.ChatId)}"));
         };
 
+    /// <summary>
+    /// Escapes special characters in a scope part so that distinct (user, chat) pairs produce distinct
+    /// composite scope keys. Backslashes are escaped first (<c>\</c> becomes <c>\\</c>), then colons
+    /// (<c>:</c> becomes <c>\:</c>), ensuring the <c>{user}::{chat}</c> format is unambiguous.
+    /// </summary>
+    private static string EscapeScopePart(string part) => part.Replace("\\", "\\\\").Replace(":", "\\:");
+
     private static HostedSessionContext GetRequiredHostedContext(AgentSession? session) =>
         session?.GetHostedContext()
             ?? throw new InvalidOperationException(

dotnet/src/Microsoft.Agents.AI.GitHub.Copilot/CopilotClientExtensions.cs

@@ -6,7 +6,7 @@ using Microsoft.Agents.AI.GitHub.Copilot;
 using Microsoft.Extensions.AI;
 using Microsoft.Shared.Diagnostics;
 
-namespace GitHub.Copilot.SDK;
+namespace GitHub.Copilot;
 
 /// <summary>
 /// Provides extension methods for <see cref="CopilotClient"/>

dotnet/src/Microsoft.Agents.AI.GitHub.Copilot/GitHubCopilotAgent.cs

@@ -9,7 +9,7 @@ using System.Text.Json;
 using System.Threading;
 using System.Threading.Channels;
 using System.Threading.Tasks;
-using GitHub.Copilot.SDK;
+using GitHub.Copilot;
 using Microsoft.Extensions.AI;
 using Microsoft.Shared.Diagnostics;
 
@@ -169,7 +169,7 @@ public sealed class GitHubCopilotAgent : AIAgent, IAsyncDisposable
             Channel<AgentResponseUpdate> channel = Channel.CreateUnbounded<AgentResponseUpdate>();
 
             // Subscribe to session events
-            using IDisposable subscription = copilotSession.On(evt =>
+            using IDisposable subscription = copilotSession.On<SessionEvent>(evt =>
             {
                 switch (evt)
                 {
@@ -210,7 +210,7 @@ public sealed class GitHubCopilotAgent : AIAgent, IAsyncDisposable
                 string prompt = string.Join("\n", messages.Select(m => m.Text));
 
                 // Handle DataContent as attachments
-                (List<UserMessageAttachmentFile>? attachments, tempDir) = await ProcessDataContentAttachmentsAsync(
+                (List<AttachmentFile>? attachments, tempDir) = await ProcessDataContentAttachmentsAsync(
                     messages,
                     cancellationToken).ConfigureAwait(false);
 
@@ -262,10 +262,7 @@ public sealed class GitHubCopilotAgent : AIAgent, IAsyncDisposable
 
     private async Task EnsureClientStartedAsync(CancellationToken cancellationToken)
     {
-        if (this._copilotClient.State != ConnectionState.Connected)
-        {
-            await this._copilotClient.StartAsync(cancellationToken).ConfigureAwait(false);
-        }
+        await this._copilotClient.StartAsync(cancellationToken).ConfigureAwait(false);
     }
 
     private ResumeSessionConfig CreateResumeConfig()
@@ -275,36 +272,18 @@ public sealed class GitHubCopilotAgent : AIAgent, IAsyncDisposable
 
     /// <summary>
     /// Copies all supported properties from a source <see cref="SessionConfig"/> into a new instance
-    /// with <see cref="SessionConfig.Streaming"/> set to <c>true</c>.
+    /// with <see cref="SessionConfigBase.Streaming"/> set to <c>true</c>.
     /// </summary>
     internal static SessionConfig CopySessionConfig(SessionConfig source)
     {
-        return new SessionConfig
-        {
-            Model = source.Model,
-            ReasoningEffort = source.ReasoningEffort,
-            Tools = source.Tools,
-            SystemMessage = source.SystemMessage,
-            AvailableTools = source.AvailableTools,
-            ExcludedTools = source.ExcludedTools,
-            Provider = source.Provider,
-            OnPermissionRequest = source.OnPermissionRequest,
-            OnUserInputRequest = source.OnUserInputRequest,
-            Hooks = source.Hooks,
-            WorkingDirectory = source.WorkingDirectory,
-            ConfigDir = source.ConfigDir,
-            McpServers = source.McpServers,
-            CustomAgents = source.CustomAgents,
-            SkillDirectories = source.SkillDirectories,
-            DisabledSkills = source.DisabledSkills,
-            InfiniteSessions = source.InfiniteSessions,
-            Streaming = true
-        };
+        SessionConfig copy = source.Clone();
+        copy.Streaming = true;
+        return copy;
     }
 
     /// <summary>
     /// Copies all supported properties from a source <see cref="SessionConfig"/> into a new
-    /// <see cref="ResumeSessionConfig"/> with <see cref="ResumeSessionConfig.Streaming"/> set to <c>true</c>.
+    /// <see cref="ResumeSessionConfig"/> with <see cref="SessionConfigBase.Streaming"/> set to <c>true</c>.
     /// </summary>
     internal static ResumeSessionConfig CopyResumeSessionConfig(SessionConfig? source)
     {
@@ -321,7 +300,7 @@ public sealed class GitHubCopilotAgent : AIAgent, IAsyncDisposable
             OnUserInputRequest = source?.OnUserInputRequest,
             Hooks = source?.Hooks,
             WorkingDirectory = source?.WorkingDirectory,
-            ConfigDir = source?.ConfigDir,
+            ConfigDirectory = source?.ConfigDirectory,
             McpServers = source?.McpServers,
             CustomAgents = source?.CustomAgents,
             SkillDirectories = source?.SkillDirectories,
@@ -394,10 +373,10 @@ public sealed class GitHubCopilotAgent : AIAgent, IAsyncDisposable
 
         AdditionalPropertiesDictionary<long>? additionalCounts = null;
 
-        if (usageEvent.Data.CacheWriteTokens is double cacheWriteTokens)
+        if (usageEvent.Data.CacheWriteTokens is long cacheWriteTokens)
         {
             additionalCounts ??= [];
-            additionalCounts[nameof(AssistantUsageData.CacheWriteTokens)] = (long)cacheWriteTokens;
+            additionalCounts[nameof(AssistantUsageData.CacheWriteTokens)] = cacheWriteTokens;
         }
 
         if (usageEvent.Data.Cost is double cost)
@@ -406,10 +385,10 @@ public sealed class GitHubCopilotAgent : AIAgent, IAsyncDisposable
             additionalCounts[nameof(AssistantUsageData.Cost)] = (long)cost;
         }
 
-        if (usageEvent.Data.Duration is double duration)
+        if (usageEvent.Data.Duration is TimeSpan duration)
         {
             additionalCounts ??= [];
-            additionalCounts[nameof(AssistantUsageData.Duration)] = (long)duration;
+            additionalCounts[nameof(AssistantUsageData.Duration)] = (long)duration.TotalMilliseconds;
         }
 
         return additionalCounts;
@@ -432,7 +411,7 @@ public sealed class GitHubCopilotAgent : AIAgent, IAsyncDisposable
 
     private static SessionConfig? GetSessionConfig(IList<AITool>? tools, string? instructions)
     {
-        List<AIFunction>? mappedTools = tools is { Count: > 0 } ? tools.OfType<AIFunction>().ToList() : null;
+        List<AIFunctionDeclaration>? mappedTools = tools is { Count: > 0 } ? tools.OfType<AIFunctionDeclaration>().ToList() : null;
         SystemMessageConfig? systemMessage = instructions is not null ? new SystemMessageConfig { Mode = SystemMessageMode.Append, Content = instructions } : null;
 
         if (mappedTools is null && systemMessage is null)
@@ -443,11 +422,11 @@ public sealed class GitHubCopilotAgent : AIAgent, IAsyncDisposable
         return new SessionConfig { Tools = mappedTools, SystemMessage = systemMessage };
     }
 
-    private static async Task<(List<UserMessageAttachmentFile>? Attachments, string? TempDir)> ProcessDataContentAttachmentsAsync(
+    private static async Task<(List<AttachmentFile>? Attachments, string? TempDir)> ProcessDataContentAttachmentsAsync(
         IEnumerable<ChatMessage> messages,
         CancellationToken cancellationToken)
     {
-        List<UserMessageAttachmentFile>? attachments = null;
+        List<AttachmentFile>? attachments = null;
         string? tempDir = null;
         foreach (ChatMessage message in messages)
         {
@@ -461,7 +440,7 @@ public sealed class GitHubCopilotAgent : AIAgent, IAsyncDisposable
                     string tempFilePath = await dataContent.SaveToAsync(tempDir, cancellationToken).ConfigureAwait(false);
 
                     attachments ??= [];
-                    attachments.Add(new UserMessageAttachmentFile
+                    attachments.Add(new AttachmentFile
                     {
                         Path = tempFilePath,
                         DisplayName = Path.GetFileName(tempFilePath)

dotnet/src/Microsoft.Agents.AI.GitHub.Copilot/Microsoft.Agents.AI.GitHub.Copilot.csproj

@@ -4,6 +4,7 @@
     <VersionSuffix>preview</VersionSuffix>
     <!-- GitHub.Copilot.SDK only supports .NET 8.0+ -->
     <TargetFrameworks>$(TargetFrameworksCore)</TargetFrameworks>
+    <NoWarn>$(NoWarn);GHCP001</NoWarn>
   </PropertyGroup>
 
   <PropertyGroup>

dotnet/src/Microsoft.Agents.AI.Harness/ChatClientHarnessExtensions.cs

@@ -16,23 +16,16 @@ public static class ChatClientHarnessExtensions
 {
     /// <summary>
     /// Creates a new <see cref="HarnessAgent"/> that wraps this <see cref="IChatClient"/> with a pre-configured
-    /// pipeline including function invocation, per-service-call chat history persistence, and in-loop compaction.
+    /// pipeline including function invocation, per-service-call chat history persistence, optional in-loop compaction, and a rich set
+    /// of default context providers and agent decorators.
     /// </summary>
     /// <param name="chatClient">
     /// The <see cref="IChatClient"/> that provides access to the underlying AI model.
     /// </param>
-    /// <param name="maxContextWindowTokens">
-    /// The maximum number of tokens the model's context window supports (e.g., 1,050,000 for gpt-5.4).
-    /// Used to configure the compaction strategy.
-    /// </param>
-    /// <param name="maxOutputTokens">
-    /// The maximum number of output tokens the model can generate per response (e.g., 128,000 for gpt-5.4).
-    /// Used to configure the compaction strategy.
-    /// </param>
     /// <param name="options">
     /// Optional configuration options for the agent, including instructions override, tools,
-    /// additional context providers, and chat history provider.
-    /// When <see langword="null"/>, the agent uses built-in default settings.
+    /// additional context providers, chat history provider, and compaction settings.
+    /// When <see langword="null"/>, the agent uses built-in default settings with compaction disabled.
     /// </param>
     /// <param name="loggerFactory">
     /// Optional logger factory for creating loggers used by the agent and its components.
@@ -43,10 +36,8 @@ public static class ChatClientHarnessExtensions
     /// <returns>A new <see cref="HarnessAgent"/> instance.</returns>
     public static HarnessAgent AsHarnessAgent(
         this IChatClient chatClient,
-        int maxContextWindowTokens,
-        int maxOutputTokens,
         HarnessAgentOptions? options = null,
         ILoggerFactory? loggerFactory = null,
         IServiceProvider? services = null) =>
-        new(chatClient, maxContextWindowTokens, maxOutputTokens, options, loggerFactory, services);
+        new(chatClient, options, loggerFactory, services);
 }

dotnet/src/Microsoft.Agents.AI.Harness/HarnessAgent.cs

@@ -18,50 +18,65 @@ namespace Microsoft.Agents.AI;
 
 /// <summary>
 /// A pre-configured <see cref="DelegatingAIAgent"/> that wraps a <see cref="ChatClientAgent"/> with
-/// function invocation, per-service-call chat history persistence, in-loop compaction, and a rich set
+/// function invocation, per-service-call chat history persistence, optional in-loop compaction, and a rich set
 /// of default context providers and agent decorators.
 /// </summary>
 /// <remarks>
 /// <para>
-/// <see cref="HarnessAgent"/> assembles the following pipeline from a caller-supplied <see cref="IChatClient"/>:
+/// <see cref="HarnessAgent"/> provides an opinionated, batteries-included agent suitable for
+/// interactive agentic scenarios such as research, coding, data analysis, and general task automation.
+/// It assembles a full pipeline from a caller-supplied <see cref="IChatClient"/> so that callers
+/// only need to configure the parts they want to customize.
+/// </para>
+/// <para>
+/// <strong>Chat client pipeline (inner to outer):</strong>
 /// <list type="number">
-/// <item><description><see cref="FunctionInvokingChatClient"/> — automatic function/tool invocation.</description></item>
-/// <item><description><see cref="MessageInjectingChatClient"/> — allows external code to inject messages into the conversation mid-stream.</description></item>
-/// <item><description><see cref="PerServiceCallChatHistoryPersistingChatClient"/> — persists chat history after every individual service call within a function-invocation loop.</description></item>
-/// <item><description><see cref="AIContextProviderChatClient"/> with a <see cref="CompactionProvider"/> — applies context-window compaction before each call so long function-invocation loops do not overflow the context window.</description></item>
+/// <item><description><see cref="FunctionInvokingChatClient"/> — automatic function/tool invocation with configurable iteration limits.</description></item>
+/// <item><description><see cref="MessageInjectingChatClient"/> — allows external code to inject messages into the conversation mid-stream (e.g., for user interrupts).</description></item>
+/// <item><description><see cref="PerServiceCallChatHistoryPersistingChatClient"/> — persists chat history after every individual service call within a function-invocation loop, enabling crash recovery and history inspection.</description></item>
+/// <item><description><see cref="AIContextProviderChatClient"/> with a <see cref="CompactionProvider"/> — applies context-window compaction before each call so long function-invocation loops do not overflow the context window. Only included when <see cref="HarnessAgentOptions.MaxContextWindowTokens"/> and <see cref="HarnessAgentOptions.MaxOutputTokens"/> are both provided.</description></item>
 /// </list>
 /// </para>
 /// <para>
-/// By default, the following context providers are included (each can be disabled via <see cref="HarnessAgentOptions"/>):
+/// <strong>Context providers (each enabled by default, individually disableable via <see cref="HarnessAgentOptions"/>):</strong>
 /// <list type="bullet">
-/// <item><description><see cref="TodoProvider"/> — todo list management.</description></item>
-/// <item><description><see cref="AgentModeProvider"/> — agent mode tracking (plan/execute).</description></item>
-/// <item><description><see cref="FileMemoryProvider"/> — file-based session memory.</description></item>
-/// <item><description><see cref="FileAccessProvider"/> — shared file access.</description></item>
-/// <item><description><see cref="AgentSkillsProvider"/> — skill discovery and loading.</description></item>
+/// <item><description><see cref="TodoProvider"/> — persistent todo list that the agent uses to track multi-step plans. Disable with <see cref="HarnessAgentOptions.DisableTodoProvider"/>.</description></item>
+/// <item><description><see cref="AgentModeProvider"/> — mode tracking (e.g., "plan" vs "execute") that the agent uses to structure its work. Disable with <see cref="HarnessAgentOptions.DisableAgentModeProvider"/>.</description></item>
+/// <item><description><see cref="FileMemoryProvider"/> — file-based session memory allowing the agent to persist notes and artifacts across turns. Disable with <see cref="HarnessAgentOptions.DisableFileMemory"/>.</description></item>
+/// <item><description><see cref="FileAccessProvider"/> — shared file access providing read/write tools for a working directory. Disable with <see cref="HarnessAgentOptions.DisableFileAccess"/>.</description></item>
+/// <item><description><see cref="AgentSkillsProvider"/> — discovers and loads skill definitions from the file system, enabling dynamic tool sets. Disable with <see cref="HarnessAgentOptions.DisableAgentSkillsProvider"/>.</description></item>
 /// </list>
 /// </para>
 /// <para>
-/// The agent is also wrapped with the following decorators by default (each can be disabled):
+/// <strong>Optional context providers (enabled via <see cref="HarnessAgentOptions"/>):</strong>
 /// <list type="bullet">
-/// <item><description><see cref="ToolApprovalAgent"/> — "don't ask again" tool approval rules.</description></item>
-/// <item><description><see cref="OpenTelemetryAgent"/> — OpenTelemetry instrumentation.</description></item>
+/// <item><description><see cref="BackgroundAgentsProvider"/> — enables delegation to background agents for parallel work. Enable by setting <see cref="HarnessAgentOptions.BackgroundAgents"/>.</description></item>
+/// <item><description><c>ShellEnvironmentProvider</c> — injects OS/shell/CWD information and a shell execution tool. Enable by setting <c>HarnessAgentOptions.ShellExecutor</c> (.NET only).</description></item>
 /// </list>
 /// </para>
 /// <para>
-/// A <see cref="HostedWebSearchTool"/> is added to the chat options by default (can be disabled via
-/// <see cref="HarnessAgentOptions.DisableWebSearch"/>).
+/// <strong>Agent decorators (each enabled by default, individually disableable):</strong>
+/// <list type="bullet">
+/// <item><description><see cref="ToolApprovalAgent"/> — "don't ask again" tool approval rules enabling safe unattended execution. Disable with <see cref="HarnessAgentOptions.DisableToolApproval"/>.</description></item>
+/// <item><description><see cref="OpenTelemetryAgent"/> — OpenTelemetry instrumentation following semantic conventions for generative AI. Disable with <see cref="HarnessAgentOptions.DisableOpenTelemetry"/>.</description></item>
+/// </list>
 /// </para>
 /// <para>
-/// The underlying <see cref="ChatClientAgent"/> is configured with
-/// <see cref="ChatClientAgentOptions.UseProvidedChatClientAsIs"/> and
-/// <see cref="ChatClientAgentOptions.RequirePerServiceCallChatHistoryPersistence"/> set to <see langword="true"/>
-/// to match the manually-assembled pipeline.
+/// <strong>Default tools:</strong>
+/// <list type="bullet">
+/// <item><description><see cref="HostedWebSearchTool"/> — a hosted web search tool added to chat options by default. Disable with <see cref="HarnessAgentOptions.DisableWebSearch"/>.</description></item>
+/// </list>
 /// </para>
 /// <para>
-/// When no <see cref="HarnessAgentOptions.ChatHistoryProvider"/> is supplied, the agent defaults to an
-/// <see cref="InMemoryChatHistoryProvider"/> whose chat reducer applies the same compaction strategy,
-/// keeping in-memory history from growing unboundedly across sessions.
+/// <strong>Chat history:</strong> When no <see cref="HarnessAgentOptions.ChatHistoryProvider"/> is supplied,
+/// the agent defaults to an <see cref="InMemoryChatHistoryProvider"/>. If compaction is enabled, the provider
+/// is configured with a compaction-based chat reducer to keep in-memory history bounded. Otherwise, no reducer
+/// is applied.
+/// </para>
+/// <para>
+/// <strong>Default instructions:</strong> The agent includes built-in system instructions (<see cref="DefaultInstructions"/>)
+/// that guide general tool usage and reasoning patterns. These can be overridden via <see cref="HarnessAgentOptions.HarnessInstructions"/>
+/// and combined with agent-specific instructions via <see cref="ChatOptions.Instructions"/>.
 /// </para>
 /// </remarks>
 [Experimental(DiagnosticIds.Experiments.AgentsAIExperiments)]
@@ -90,21 +105,13 @@ public sealed class HarnessAgent : DelegatingAIAgent
     /// </summary>
     /// <param name="chatClient">
     /// The <see cref="IChatClient"/> that provides access to the underlying AI model.
-    /// The agent wraps this client in a function-invocation, per-service-call persistence,
-    /// and compaction pipeline automatically.
-    /// </param>
-    /// <param name="maxContextWindowTokens">
-    /// The maximum number of tokens the model's context window supports (e.g., 1,050,000 for gpt-5.4).
-    /// Used to configure the compaction strategy.
-    /// </param>
-    /// <param name="maxOutputTokens">
-    /// The maximum number of output tokens the model can generate per response (e.g., 128,000 for gpt-5.4).
-    /// Used to configure the compaction strategy and to limit the model's output.
+    /// The agent wraps this client in a function-invocation and per-service-call persistence pipeline.
+    /// When compaction is enabled via <paramref name="options"/>, a compaction decorator is also added.
     /// </param>
     /// <param name="options">
     /// Optional configuration options for the agent, including instructions override, tools,
-    /// additional context providers, and chat history provider.
-    /// When <see langword="null"/>, the agent uses built-in default settings.
+    /// additional context providers, chat history provider, and compaction settings.
+    /// When <see langword="null"/>, the agent uses built-in default settings with compaction disabled.
     /// </param>
     /// <param name="loggerFactory">
     /// Optional logger factory for creating loggers used by the agent and its components.
@@ -116,23 +123,22 @@ public sealed class HarnessAgent : DelegatingAIAgent
     /// <paramref name="chatClient"/> is <see langword="null"/>.
     /// </exception>
     /// <exception cref="ArgumentOutOfRangeException">
-    /// <paramref name="maxContextWindowTokens"/> is not positive, or
-    /// <paramref name="maxOutputTokens"/> is negative or greater than or equal to <paramref name="maxContextWindowTokens"/>.
+    /// <see cref="HarnessAgentOptions.MaxContextWindowTokens"/> is not positive, or
+    /// <see cref="HarnessAgentOptions.MaxOutputTokens"/> is negative or greater than or equal to
+    /// <see cref="HarnessAgentOptions.MaxContextWindowTokens"/> (when both are provided).
     /// </exception>
-    public HarnessAgent(IChatClient chatClient, int maxContextWindowTokens, int maxOutputTokens, HarnessAgentOptions? options = null, ILoggerFactory? loggerFactory = null, IServiceProvider? services = null)
+    public HarnessAgent(IChatClient chatClient, HarnessAgentOptions? options = null, ILoggerFactory? loggerFactory = null, IServiceProvider? services = null)
         : base(BuildAgent(
             Throw.IfNull(chatClient),
-            maxContextWindowTokens,
-            maxOutputTokens,
             options,
             loggerFactory,
             services))
     {
     }
 
-    private static AIAgent BuildAgent(IChatClient chatClient, int maxContextWindowTokens, int maxOutputTokens, HarnessAgentOptions? options, ILoggerFactory? loggerFactory, IServiceProvider? services)
+    private static AIAgent BuildAgent(IChatClient chatClient, HarnessAgentOptions? options, ILoggerFactory? loggerFactory, IServiceProvider? services)
     {
-        ChatClientAgent innerAgent = BuildInnerAgent(chatClient, maxContextWindowTokens, maxOutputTokens, options, loggerFactory, services);
+        ChatClientAgent innerAgent = BuildInnerAgent(chatClient, options, loggerFactory, services);
 
         AIAgentBuilder builder = innerAgent.AsBuilder();
 
@@ -149,17 +155,35 @@ public sealed class HarnessAgent : DelegatingAIAgent
         return builder.Build(services);
     }
 
-    private static ChatClientAgent BuildInnerAgent(IChatClient chatClient, int maxContextWindowTokens, int maxOutputTokens, HarnessAgentOptions? options, ILoggerFactory? loggerFactory, IServiceProvider? services)
+    private static ChatClientAgent BuildInnerAgent(IChatClient chatClient, HarnessAgentOptions? options, ILoggerFactory? loggerFactory, IServiceProvider? services)
     {
-        var compactionStrategy = new ContextWindowCompactionStrategy(
-            maxContextWindowTokens: maxContextWindowTokens,
-            maxOutputTokens: maxOutputTokens);
+        // Determine compaction strategy:
+        // 1. DisableCompaction = true → no compaction
+        // 2. Custom CompactionStrategy provided → use it (ignore token params)
+        // 3. Both token params provided → build default ContextWindowCompactionStrategy
+        // 4. Otherwise → no compaction
+        CompactionStrategy? compactionStrategy = null;
+        if (options?.DisableCompaction is not true)
+        {
+            if (options?.CompactionStrategy is CompactionStrategy customStrategy)
+            {
+                compactionStrategy = customStrategy;
+            }
+            else if (options?.MaxContextWindowTokens is int maxCtx && options?.MaxOutputTokens is int maxOut)
+            {
+                compactionStrategy = new ContextWindowCompactionStrategy(
+                    maxContextWindowTokens: maxCtx,
+                    maxOutputTokens: maxOut);
+            }
+        }
 
         ChatHistoryProvider chatHistoryProvider = options?.ChatHistoryProvider
-            ?? new InMemoryChatHistoryProvider(new InMemoryChatHistoryProviderOptions
-            {
-                ChatReducer = compactionStrategy.AsChatReducer(),
-            });
+            ?? (compactionStrategy is not null
+                ? new InMemoryChatHistoryProvider(new InMemoryChatHistoryProviderOptions
+                {
+                    ChatReducer = compactionStrategy.AsChatReducer(),
+                })
+                : new InMemoryChatHistoryProvider());
 
         string harnessInstructions = options?.HarnessInstructions ?? DefaultInstructions;
         string? agentInstructions = options?.ChatOptions?.Instructions;
@@ -172,20 +196,34 @@ public sealed class HarnessAgent : DelegatingAIAgent
             (false, false) => $"{harnessInstructions}\n\n{agentInstructions}",
         };
 
-        ChatOptions chatOptions = BuildChatOptions(options, instructions, maxOutputTokens);
+        ChatOptions chatOptions = BuildChatOptions(options, instructions, options?.MaxOutputTokens);
 
-        var compactionProvider = new CompactionProvider(compactionStrategy, loggerFactory: loggerFactory);
+        CompactionProvider? compactionProvider = compactionStrategy is not null
+            ? new CompactionProvider(compactionStrategy, loggerFactory: loggerFactory)
+            : null;
 
         IEnumerable<AIContextProvider> contextProviders = BuildContextProviders(options, loggerFactory);
 
-        return chatClient
-            .AsBuilder()
+        ChatClientBuilder chatClientBuilder = chatClient.AsBuilder();
+
+        if (options?.DisableNonApprovalRequiredFunctionBypassing is not true)
+        {
+            chatClientBuilder.UseNonApprovalRequiredFunctionBypassing();
+        }
+
+        ChatClientBuilder pipeline = chatClientBuilder
             .UseFunctionInvocation(loggerFactory, configure: options?.MaximumIterationsPerRequest is int maxIterations
                 ? ficc => ficc.MaximumIterationsPerRequest = maxIterations
                 : null)
             .UseMessageInjection()
-            .UsePerServiceCallChatHistoryPersistence()
-            .UseAIContextProviders(compactionProvider)
+            .UsePerServiceCallChatHistoryPersistence();
+
+        if (compactionProvider is not null)
+        {
+            pipeline = pipeline.UseAIContextProviders(compactionProvider);
+        }
+
+        return pipeline
             .BuildAIAgent(new ChatClientAgentOptions
             {
                 Id = options?.Id,
@@ -203,11 +241,15 @@ public sealed class HarnessAgent : DelegatingAIAgent
             services);
     }
 
-    private static ChatOptions BuildChatOptions(HarnessAgentOptions? options, string instructions, int maxOutputTokens)
+    private static ChatOptions BuildChatOptions(HarnessAgentOptions? options, string instructions, int? maxOutputTokens)
     {
         ChatOptions result = options?.ChatOptions?.Clone() ?? new ChatOptions();
         result.Instructions = instructions;
-        result.MaxOutputTokens ??= maxOutputTokens;
+
+        if (maxOutputTokens.HasValue)
+        {
+            result.MaxOutputTokens ??= maxOutputTokens.Value;
+        }
 
         if (options?.DisableWebSearch is not true)
         {

dotnet/src/Microsoft.Agents.AI.Harness/HarnessAgentOptions.cs

@@ -2,6 +2,7 @@
 
 using System.Collections.Generic;
 using System.Diagnostics.CodeAnalysis;
+using Microsoft.Agents.AI.Compaction;
 #if NET
 using Microsoft.Agents.AI.Tools.Shell;
 #endif
@@ -31,6 +32,68 @@ public sealed class HarnessAgentOptions
     /// </summary>
     public string? Description { get; set; }
 
+    /// <summary>
+    /// Gets or sets the maximum number of tokens the model's context window supports (e.g., 1,050,000 for gpt-5.4).
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// When both <see cref="MaxContextWindowTokens"/> and <see cref="MaxOutputTokens"/> are provided (and no
+    /// custom <see cref="CompactionStrategy"/> is set), a default <see cref="ContextWindowCompactionStrategy"/>
+    /// is constructed from these values to prevent function-invocation loops from overflowing the context window.
+    /// </para>
+    /// <para>
+    /// Ignored when <see cref="CompactionStrategy"/> is provided or when <see cref="DisableCompaction"/> is
+    /// <see langword="true"/>.
+    /// </para>
+    /// </remarks>
+    public int? MaxContextWindowTokens { get; set; }
+
+    /// <summary>
+    /// Gets or sets the maximum number of output tokens the model can generate per response (e.g., 128,000 for gpt-5.4).
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// When set, this value is used as the default for <see cref="ChatOptions"/>.<see cref="ChatOptions.MaxOutputTokens"/>
+    /// when not explicitly configured.
+    /// </para>
+    /// <para>
+    /// For compaction purposes, this value is used together with <see cref="MaxContextWindowTokens"/> to construct a
+    /// default <see cref="ContextWindowCompactionStrategy"/> — but only when no custom <see cref="CompactionStrategy"/>
+    /// is provided and <see cref="DisableCompaction"/> is <see langword="false"/>.
+    /// </para>
+    /// </remarks>
+    public int? MaxOutputTokens { get; set; }
+
+    /// <summary>
+    /// Gets or sets a custom <see cref="Compaction.CompactionStrategy"/> to use for in-loop context-window compaction.
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// When provided, this strategy is used directly and <see cref="MaxContextWindowTokens"/> and
+    /// <see cref="MaxOutputTokens"/> are ignored for compaction purposes (<see cref="MaxOutputTokens"/> is still
+    /// used as the default for <see cref="ChatOptions"/>.<see cref="ChatOptions.MaxOutputTokens"/> if set).
+    /// </para>
+    /// <para>
+    /// When <see langword="null"/> and both <see cref="MaxContextWindowTokens"/> and <see cref="MaxOutputTokens"/>
+    /// are provided, a default <see cref="ContextWindowCompactionStrategy"/> is constructed from those values.
+    /// </para>
+    /// <para>
+    /// This property is ignored when <see cref="DisableCompaction"/> is <see langword="true"/>.
+    /// </para>
+    /// </remarks>
+    public CompactionStrategy? CompactionStrategy { get; set; }
+
+    /// <summary>
+    /// Gets or sets a value indicating whether in-loop compaction is disabled.
+    /// </summary>
+    /// <remarks>
+    /// When <see langword="true"/>, compaction is disabled regardless of <see cref="CompactionStrategy"/>,
+    /// <see cref="MaxContextWindowTokens"/>, or <see cref="MaxOutputTokens"/> settings. No
+    /// <see cref="CompactionProvider"/> is added to the chat client pipeline, and the default
+    /// <see cref="InMemoryChatHistoryProvider"/> is configured without a chat reducer.
+    /// </remarks>
+    public bool DisableCompaction { get; set; }
+
     /// <summary>
     /// Gets or sets additional chat options such as tools for the agent to use.
     /// </summary>
@@ -68,9 +131,9 @@ public sealed class HarnessAgentOptions
     /// Gets or sets the <see cref="ChatHistoryProvider"/> to use for storing chat history.
     /// </summary>
     /// <remarks>
-    /// When <see langword="null"/>, the agent defaults to an <see cref="InMemoryChatHistoryProvider"/>
-    /// configured with a compaction-based chat reducer derived from the <c>maxContextWindowTokens</c>
-    /// and <c>maxOutputTokens</c> constructor parameters of <see cref="HarnessAgent"/>.
+    /// When <see langword="null"/>, the agent defaults to an <see cref="InMemoryChatHistoryProvider"/>.
+    /// If <see cref="MaxContextWindowTokens"/> and <see cref="MaxOutputTokens"/> are both provided,
+    /// the default provider is configured with a compaction-based chat reducer; otherwise, no reducer is applied.
     /// </remarks>
     public ChatHistoryProvider? ChatHistoryProvider { get; set; }
 
@@ -110,6 +173,20 @@ public sealed class HarnessAgentOptions
     /// </remarks>
     public ToolApprovalAgentOptions? ToolApprovalAgentOptions { get; set; }
 
+    /// <summary>
+    /// Gets or sets a value indicating whether bypassing of approval requests for tools that do not
+    /// require approval is disabled.
+    /// </summary>
+    /// <remarks>
+    /// When <see langword="false"/> (the default), the underlying chat client pipeline includes the decorator
+    /// added by <see cref="ChatClientBuilderExtensions.UseNonApprovalRequiredFunctionBypassing"/> above the
+    /// function invocation middleware.
+    /// This stores automatically approved function calls for tools that do not require approval in the session
+    /// state when they are returned alongside tools that do, so that only tools that truly require human
+    /// approval are surfaced to the caller.
+    /// </remarks>
+    public bool DisableNonApprovalRequiredFunctionBypassing { get; set; }
+
     /// <summary>
     /// Gets or sets a value indicating whether the <see cref="FileMemoryProvider"/> is disabled.
     /// </summary>

dotnet/src/Microsoft.Agents.AI.Hosting.AspNetCore/ClaimsIdentitySessionIsolationKeyProvider.cs

@@ -21,6 +21,18 @@ namespace Microsoft.Agents.AI.Hosting;
 /// from the ambient <see cref="HttpContext"/>.
 /// </para>
 /// <para>
+/// <strong>Security warning:</strong> The configured <see cref="ClaimsIdentitySessionIsolationKeyProviderOptions.ClaimType"/>
+/// must uniquely identify the principal within the served population. Display names, usernames, email
+/// aliases, and other mutable or non-unique claims are <strong>unsafe</strong> isolation keys unless the
+/// host can prove their uniqueness across all callers: two distinct principals that share the same value
+/// would receive the same isolation key and could read or overwrite one another's persisted sessions.
+/// The default claim type is <see cref="ClaimTypes.NameIdentifier"/>, a stable unique subject identifier
+/// that is typically populated from the OpenID Connect <c>sub</c> claim via the default JWT inbound claim
+/// mapping (note that this differs from Entra's object identifier <c>oid</c> claim; override
+/// <see cref="ClaimsIdentitySessionIsolationKeyProviderOptions.ClaimType"/> if you need <c>oid</c> or your
+/// provider maps a different claim).
+/// </para>
+/// <para>
 /// If the <see cref="HttpContext"/> is unavailable, the user is not authenticated, or the specified claim
 /// is missing, the provider returns <see langword="null"/>. The consuming <see cref="IsolationKeyScopedAgentSessionStore"/>
 /// will then enforce strict or pass-through behavior based on its configuration.
@@ -60,18 +72,24 @@ public class ClaimsIdentitySessionIsolationKeyProvider : SessionIsolationKeyProv
     /// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests.</param>
     /// <returns>
     /// A task that represents the asynchronous operation. The task result contains the value of the
-    /// configured claim type from the current user's identity, or <see langword="null"/> if the claim
-    /// is not present or the HTTP context is unavailable.
+    /// configured claim type from the current user's identity, or <see langword="null"/> if the HTTP
+    /// context is unavailable, the user is not authenticated, or the claim is not present.
     /// </returns>
     /// <remarks>
-    /// This method retrieves the claim value from <c>HttpContext.User.Claims</c>. If multiple claims
-    /// of the specified type exist, the first match is returned.
+    /// This method only reads claims from an authenticated principal: if the current request has no
+    /// authenticated user, it returns <see langword="null"/> rather than trusting claims on an
+    /// unauthenticated identity. The claim value is retrieved from <c>HttpContext.User.Claims</c>; if
+    /// multiple claims of the specified type exist, the first match is returned.
     /// </remarks>
     public override ValueTask<string?> GetSessionIsolationKeyAsync(CancellationToken cancellationToken = default)
     {
-        Claim? claim = this._httpContextAccessor?
-                           .HttpContext?
-                           .User?.Claims.FirstOrDefault(c => c.Type == this._claimType);
+        ClaimsPrincipal? user = this._httpContextAccessor?.HttpContext?.User;
+        if (user?.Identity?.IsAuthenticated != true)
+        {
+            return new ValueTask<string?>((string?)null);
+        }
+
+        Claim? claim = user?.Claims.FirstOrDefault(c => c.Type == this._claimType);
 
         return new ValueTask<string?>(claim?.Value);
     }

dotnet/src/Microsoft.Agents.AI.Hosting.AspNetCore/ClaimsIdentitySessionIsolationKeyProviderOptions.cs

@@ -14,17 +14,30 @@ public class ClaimsIdentitySessionIsolationKeyProviderOptions
     /// </summary>
     /// <remarks>
     /// <para>
-    /// Defaults to <see cref="ClaimsIdentity.DefaultNameClaimType"/>, which typically corresponds to
-    /// the user's name or unique identifier claim.
+    /// Defaults to <see cref="ClaimTypes.NameIdentifier"/>, which corresponds to a stable, unique
+    /// subject identifier for the authenticated principal. For OpenID Connect tokens (including those
+    /// issued by Microsoft Entra ID), this is typically populated from the <c>sub</c> claim via the
+    /// default JWT inbound claim mapping. Note that <c>sub</c> is distinct from Entra's object
+    /// identifier (<c>oid</c>) claim; if you require the <c>oid</c> claim, or your provider does not map
+    /// a unique identifier onto <see cref="ClaimTypes.NameIdentifier"/>, override <see cref="ClaimType"/>
+    /// with the appropriate claim type.
+    /// </para>
+    /// <para>
+    /// <strong>Security warning:</strong> The configured claim must uniquely identify the principal
+    /// within the served population. Display names (<see cref="ClaimsIdentity.DefaultNameClaimType"/>
+    /// / <see cref="ClaimTypes.Name"/>), usernames, email aliases, and other mutable or non-unique
+    /// claims are <strong>unsafe</strong> isolation keys unless the host can prove their uniqueness
+    /// across all callers. Two distinct principals that share the same value for a non-unique claim
+    /// would receive the same session-isolation key and could read or overwrite one another's
+    /// persisted sessions. Only override this value with a claim that is guaranteed unique and stable.
     /// </para>
     /// <para>
     /// Common alternatives include:
     /// <list type="bullet">
-    /// <item><description><c>ClaimTypes.NameIdentifier</c> — Stable user identifier</description></item>
-    /// <item><description><c>ClaimTypes.Email</c> — Email address</description></item>
-    /// <item><description>Custom claim types specific to your authentication provider</description></item>
+    /// <item><description>A composite of tenant and subject identifiers — required for multi-tenant hosts where the subject is only unique per tenant</description></item>
+    /// <item><description>Custom claim types specific to your authentication provider, provided they are unique and stable</description></item>
     /// </list>
     /// </para>
     /// </remarks>
-    public string ClaimType { get; set; } = ClaimsIdentity.DefaultNameClaimType;
+    public string ClaimType { get; set; } = ClaimTypes.NameIdentifier;
 }

dotnet/src/Microsoft.Agents.AI.Hosting.AspNetCore/ServiceCollectionExtensions.cs

@@ -1,6 +1,7 @@
 // Copyright (c) Microsoft. All rights reserved.
 
 using System;
+using System.Security.Claims;
 using Microsoft.AspNetCore.Http;
 using Microsoft.Extensions.DependencyInjection;
 
@@ -19,8 +20,28 @@ public static class ServiceCollectionExtensions
     /// <param name="options"> Optional configuration for the claims-based session isolation key provider.</param>
     /// <returns>The <see cref="IServiceCollection"/> so that additional calls can be chained.</returns>
     /// <remarks>
+    /// <para>
     /// This method requires <see cref="IHttpContextAccessor"/> to be registered in the service collection.
     /// Ensure that <c>services.AddHttpContextAccessor()</c> has been called before using this method.
+    /// </para>
+    /// <para>
+    /// When <paramref name="options"/> is not supplied, the isolation key is derived from the
+    /// <see cref="ClaimTypes.NameIdentifier"/> claim, a stable unique subject identifier. For OpenID
+    /// Connect tokens (including Microsoft Entra ID), this is typically mapped from the <c>sub</c> claim
+    /// by the default JWT inbound claim mapping. Authentication schemes that do not project a unique
+    /// identifier onto <see cref="ClaimTypes.NameIdentifier"/> (or hosts that require a different claim
+    /// such as Entra's <c>oid</c>) should override
+    /// <see cref="ClaimsIdentitySessionIsolationKeyProviderOptions.ClaimType"/>; otherwise the key may be
+    /// absent, which causes strict-mode session stores to fail.
+    /// </para>
+    /// <para>
+    /// <strong>Security warning:</strong> If you override
+    /// <see cref="ClaimsIdentitySessionIsolationKeyProviderOptions.ClaimType"/>, the chosen claim must
+    /// uniquely identify the principal within the served population. Display names, usernames, email
+    /// aliases, and other mutable or non-unique claims are <strong>unsafe</strong> isolation keys unless
+    /// the host can prove their uniqueness across all callers, because distinct principals that share the
+    /// same claim value would receive the same isolation key and could access one another's sessions.
+    /// </para>
     /// </remarks>
     public static IServiceCollection UseClaimsBasedSessionIsolation(
         this IServiceCollection services,

dotnet/src/Microsoft.Agents.AI.Workflows/Specialized/Magentic/MagenticConstants.cs

@@ -5,4 +5,5 @@ namespace Microsoft.Agents.AI.Workflows.Specialized.Magentic;
 internal static class MagenticConstants
 {
     public const string MagenticTaskContextKey = nameof(MagenticTaskContextKey);
+    public const string CurrentSpeakerStateKey = nameof(CurrentSpeakerStateKey);
 }

dotnet/src/Microsoft.Agents.AI.Workflows/Specialized/Magentic/MagenticOrchestrator.cs

@@ -90,6 +90,7 @@ internal class MagenticOrchestrator(AIAgent managerAgent, List<AIAgent> team, Ta
 
     private MagenticTaskContext? _taskContext;
     private PortBinding? _planReviewPort;
+    private string? _currentSpeakerExecutorId;
 
     protected override ProtocolBuilder ConfigureProtocol(ProtocolBuilder protocolBuilder)
     {
@@ -196,15 +197,46 @@ internal class MagenticOrchestrator(AIAgent managerAgent, List<AIAgent> team, Ta
         else
         {
             // Subsequent turns: agent returned control, go directly to coordination (progress ledger only, no replan).
-            // Capture the participant's reply into the manager-visible chat history so the progress ledger can see it.
             if (messages is { Count: > 0 })
             {
+                // Capture the participant's reply into the manager-visible chat history so the progress ledger can see it.
                 this._taskContext.ChatHistory.AddRange(messages);
+
+                // Share the reply with the other participants except the replier
+                await this.BroadcastReplyToOtherParticipantsAsync(messages, context, cancellationToken).ConfigureAwait(false);
             }
             await this.RunCoordinationRoundAsync(this._taskContext, context, cancellationToken).ConfigureAwait(false);
         }
     }
 
+    /// <summary>
+    /// Forwards a participant's reply to every other participant so they share the running conversation.
+    /// The messages are buffered (no <see cref="TurnToken"/> is sent) - they only become context for the participant's next turn.
+    /// </summary>
+    private ValueTask BroadcastReplyToOtherParticipantsAsync(
+        List<ChatMessage> messages, IWorkflowContext context, CancellationToken cancellationToken)
+    {
+        // Without a known current speaker we cannot exclude the reply's author, so skip the broadcast
+        // rather than risk echoing the reply back to its own author. This covers the window after a
+        // checkpoint restore but before any delegation has set the current speaker.
+        if (string.IsNullOrEmpty(this._currentSpeakerExecutorId))
+        {
+            return default;
+        }
+
+        List<Task>? sendTasks = null;
+        foreach (AIAgent agent in team)
+        {
+            string executorId = AIAgentHostExecutor.IdFor(agent);
+            if (string.Equals(executorId, this._currentSpeakerExecutorId, StringComparison.Ordinal))
+            {
+                continue;
+            }
+            (sendTasks ??= []).Add(context.SendMessageAsync(messages, executorId, cancellationToken).AsTask());
+        }
+        return sendTasks is null ? default : new ValueTask(Task.WhenAll(sendTasks));
+    }
+
     private ChatMessage? _fullTaskLedgerMessage;
     private ValueTask DelegateToTeamAsync(MagenticTaskContext taskContext, IWorkflowContext context, CancellationToken cancellationToken)
     {
@@ -287,15 +319,18 @@ internal class MagenticOrchestrator(AIAgent managerAgent, List<AIAgent> team, Ta
             return;
         }
 
+        string nextExecutorId = AIAgentHostExecutor.IdFor(nextAgent);
+
         if (!string.IsNullOrWhiteSpace(taskContext.ProgressLedger.InstructionOrQuestion))
         {
             ChatMessage instruction = new(ChatRole.Assistant, taskContext.ProgressLedger.InstructionOrQuestion);
             taskContext.ChatHistory.Add(instruction);
 
-            await context.SendMessageAsync(instruction, cancellationToken).ConfigureAwait(false);
+            // Target the instruction at the chosen speaker only.
+            await context.SendMessageAsync(instruction, nextExecutorId, cancellationToken).ConfigureAwait(false);
         }
 
-        string nextExecutorId = AIAgentHostExecutor.IdFor(nextAgent);
+        this._currentSpeakerExecutorId = nextExecutorId;
         await context.SendMessageAsync(new TurnToken(taskContext.EmitUpdateEvents), nextExecutorId, cancellationToken).ConfigureAwait(false);
     }
 
@@ -303,6 +338,7 @@ internal class MagenticOrchestrator(AIAgent managerAgent, List<AIAgent> team, Ta
     {
         bool wasStalled = taskContext.IsStalled;
         taskContext.Reset();
+        this._currentSpeakerExecutorId = null;
         await context.SendMessageAsync(new ResetChatSignal(), cancellationToken: cancellationToken).ConfigureAwait(false);
 
         await this.UpdatePlanAndDelegateAsync(taskContext, context, cancellationToken, replanAfterStall: wasStalled).ConfigureAwait(false);
@@ -313,9 +349,9 @@ internal class MagenticOrchestrator(AIAgent managerAgent, List<AIAgent> team, Ta
         List<ChatMessage> messages = [await this._manager.PrepareFinalAnswerAsync(taskContext, context, cancellationToken).ConfigureAwait(false)];
         await context.YieldOutputAsync(messages, cancellationToken).ConfigureAwait(false);
         taskContext.IsTerminated = true;
+        this._currentSpeakerExecutorId = null;
     }
 
-    private const string CurrentTurnEmitUpdateEventsKey = nameof(CurrentTurnEmitUpdateEventsKey);
     protected internal override async ValueTask OnCheckpointingAsync(IWorkflowContext context, CancellationToken cancellationToken = default)
     {
         Task contextStateTask = this._taskContext == null
@@ -325,14 +361,21 @@ internal class MagenticOrchestrator(AIAgent managerAgent, List<AIAgent> team, Ta
                                                               cancellationToken: cancellationToken)
                                        .AsTask();
 
+        Task currentSpeakerTask = context.QueueStateUpdateAsync(MagenticConstants.CurrentSpeakerStateKey,
+                                                            this._currentSpeakerExecutorId,
+                                                            cancellationToken: cancellationToken)
+                                        .AsTask();
+
         await Task.WhenAll(base.OnCheckpointingAsync(context, cancellationToken).AsTask(),
-                           contextStateTask).ConfigureAwait(false);
+                           contextStateTask,
+                           currentSpeakerTask).ConfigureAwait(false);
     }
 
     protected internal override async ValueTask OnCheckpointRestoredAsync(IWorkflowContext context, CancellationToken cancellationToken = default)
     {
-        await Task.WhenAll(base.OnCheckpointRestoredAsync(context, cancellationToken).AsTask(), LoadContextStateAsync())
-                  .ConfigureAwait(false);
+        await Task.WhenAll(base.OnCheckpointRestoredAsync(context, cancellationToken).AsTask(),
+                            LoadContextStateAsync(),
+                            LoadCurrentSpeakerAsync()).ConfigureAwait(false);
 
         async Task LoadContextStateAsync()
         {
@@ -344,5 +387,11 @@ internal class MagenticOrchestrator(AIAgent managerAgent, List<AIAgent> team, Ta
                 this._taskContext = new MagenticTaskContext(state, team, limits, []);
             }
         }
+
+        async Task LoadCurrentSpeakerAsync()
+        {
+            this._currentSpeakerExecutorId = await context.ReadStateAsync<string?>(MagenticConstants.CurrentSpeakerStateKey, cancellationToken: cancellationToken)
+                                                        .ConfigureAwait(false);
+        }
     }
 }

dotnet/src/Microsoft.Agents.AI/ChatClient/ChatClientAgent.cs

@@ -38,6 +38,8 @@ namespace Microsoft.Agents.AI;
 /// </remarks>
 public sealed partial class ChatClientAgent : AIAgent
 {
+    private const string AGUIProviderName = "ag-ui";
+
     private readonly ChatClientAgentOptions? _agentOptions;
     private readonly HashSet<string> _aiContextProviderStateKeys;
     private readonly AIAgentMetadata _agentMetadata;
@@ -562,6 +564,7 @@ public sealed partial class ChatClientAgent : AIAgent
         requestChatOptions.ModelId ??= this._agentOptions.ChatOptions.ModelId;
         requestChatOptions.PresencePenalty ??= this._agentOptions.ChatOptions.PresencePenalty;
         requestChatOptions.ResponseFormat ??= this._agentOptions.ChatOptions.ResponseFormat;
+        requestChatOptions.Reasoning ??= this._agentOptions.ChatOptions.Reasoning;
         requestChatOptions.Seed ??= this._agentOptions.ChatOptions.Seed;
         requestChatOptions.Temperature ??= this._agentOptions.ChatOptions.Temperature;
         requestChatOptions.TopP ??= this._agentOptions.ChatOptions.TopP;
@@ -815,7 +818,7 @@ public sealed partial class ChatClientAgent : AIAgent
 
         if (!string.IsNullOrWhiteSpace(responseConversationId))
         {
-            if (this._agentOptions?.ChatHistoryProvider is not null)
+            if (!IsAGUIProviderName(this._agentMetadata.ProviderName) && this._agentOptions?.ChatHistoryProvider is not null)
             {
                 // The agent has a ChatHistoryProvider configured, but the service returned a conversation id,
                 // meaning the service manages chat history server-side. Both cannot be used simultaneously.
@@ -929,6 +932,9 @@ public sealed partial class ChatClientAgent : AIAgent
         }
     }
 
+    private static bool IsAGUIProviderName(string? providerName) =>
+        string.Equals(providerName, AGUIProviderName, StringComparison.Ordinal);
+
     /// <summary>
     /// Ensures that <see cref="AIAgent.CurrentRunContext"/> contains the resolved session.
     /// </summary>
@@ -976,12 +982,17 @@ public sealed partial class ChatClientAgent : AIAgent
 
     private ChatHistoryProvider? ResolveChatHistoryProvider(ChatOptions? chatOptions)
     {
-        ChatHistoryProvider? provider = chatOptions?.ConversationId is null ? this.ChatHistoryProvider : null;
+        ChatHistoryProvider? provider =
+            chatOptions?.ConversationId is null || IsAGUIProviderName(this._agentMetadata.ProviderName)
+            ? this.ChatHistoryProvider
+            : null;
 
         // If someone provided an override ChatHistoryProvider via AdditionalProperties, we should use that instead.
         if (chatOptions?.AdditionalProperties?.TryGetValue(out ChatHistoryProvider? overrideProvider) is true)
         {
-            if (this._agentOptions?.ThrowOnChatHistoryProviderConflict is true && string.IsNullOrWhiteSpace(chatOptions?.ConversationId) is false)
+            if (!IsAGUIProviderName(this._agentMetadata.ProviderName) &&
+                this._agentOptions?.ThrowOnChatHistoryProviderConflict is true &&
+                string.IsNullOrWhiteSpace(chatOptions?.ConversationId) is false)
             {
                 throw new InvalidOperationException(
                     $"Only {nameof(ChatClientAgentSession.ConversationId)} or {nameof(this.ChatHistoryProvider)} may be used, but not both. The current {nameof(ChatClientAgentSession)} has a {nameof(ChatClientAgentSession.ConversationId)} indicating server-side chat history management, but an override {nameof(this.ChatHistoryProvider)} was provided via {nameof(AgentRunOptions.AdditionalProperties)}.");

dotnet/tests/Microsoft.Agents.AI.AGUI.UnitTests/AGUIChatClientTests.cs

@@ -243,6 +243,46 @@ public sealed class AGUIAgentTests
         Assert.Contains(updates, u => u.Text == "Hello");
     }
 
+    [Fact]
+    public async Task RunStreamingAsync_WithSession_SendsFullHistoryAfterThreadIdIsSetAsync()
+    {
+        // Arrange
+        var captureHandler = new StateCapturingTestDelegatingHandler();
+        captureHandler.AddResponse(
+        [
+            new RunStartedEvent { ThreadId = "thread1", RunId = "run1" },
+            new TextMessageStartEvent { MessageId = "msg1", Role = AGUIRoles.Assistant },
+            new TextMessageContentEvent { MessageId = "msg1", Delta = "First response" },
+            new TextMessageEndEvent { MessageId = "msg1" },
+            new RunFinishedEvent { ThreadId = "thread1", RunId = "run1" }
+        ]);
+        captureHandler.AddResponse(
+        [
+            new RunStartedEvent { ThreadId = "thread1", RunId = "run2" },
+            new TextMessageStartEvent { MessageId = "msg2", Role = AGUIRoles.Assistant },
+            new TextMessageContentEvent { MessageId = "msg2", Delta = "Second response" },
+            new TextMessageEndEvent { MessageId = "msg2" },
+            new RunFinishedEvent { ThreadId = "thread1", RunId = "run2" }
+        ]);
+        using HttpClient httpClient = new(captureHandler);
+
+        var chatClient = new AGUIChatClient(httpClient, "http://localhost/agent", null, AGUIJsonSerializerContext.Default.Options);
+        AIAgent agent = chatClient.AsAIAgent(instructions: null, name: "agent1", description: "Test agent", tools: []);
+        AgentSession session = await agent.CreateSessionAsync();
+
+        // Act
+        await foreach (var _ in agent.RunStreamingAsync([new ChatMessage(ChatRole.User, "First")], session))
+        {
+        }
+
+        await foreach (var _ in agent.RunStreamingAsync([new ChatMessage(ChatRole.User, "Second")], session))
+        {
+        }
+
+        // Assert
+        Assert.Equal([1, 3], captureHandler.CapturedMessageCounts);
+    }
+
     [Fact]
     public async Task DeserializeSession_WithValidState_ReturnsChatClientAgentSessionAsync()
     {
@@ -1686,10 +1726,12 @@ internal sealed class CapturingTestDelegatingHandler : DelegatingHandler
 internal sealed class StateCapturingTestDelegatingHandler : DelegatingHandler
 {
     private readonly Queue<Func<HttpRequestMessage, Task<HttpResponseMessage>>> _responseFactories = new();
+    private readonly List<int> _capturedMessageCounts = [];
 
     public bool RequestWasMade { get; private set; }
     public JsonElement? CapturedState { get; private set; }
     public int CapturedMessageCount { get; private set; }
+    public IReadOnlyList<int> CapturedMessageCounts => this._capturedMessageCounts;
 
     public void AddResponse(BaseEvent[] events)
     {
@@ -1714,6 +1756,7 @@ internal sealed class StateCapturingTestDelegatingHandler : DelegatingHandler
                 this.CapturedState = input.State;
             }
             this.CapturedMessageCount = input.Messages.Count();
+            this._capturedMessageCounts.Add(this.CapturedMessageCount);
         }
 
         if (this._responseFactories.Count == 0)

dotnet/tests/Microsoft.Agents.AI.DurableTask.IntegrationTests/WorkflowConsoleAppSamplesValidation.cs

@@ -182,7 +182,7 @@ public sealed class WorkflowConsoleAppSamplesValidation(ITestOutputHelper output
         }
     }
 
-    [RetryFact(2, 5000)]
+    [RetryFact(2, 5000, Skip = "KeyNotFoundException in workflow execution. See https://github.com/microsoft/agent-framework/issues/6404")]
     public async Task WorkflowEventsSampleValidationAsync()
     {
         using CancellationTokenSource testTimeoutCts = this.CreateTestTimeoutCts(s_testTimeout);
@@ -278,7 +278,7 @@ public sealed class WorkflowConsoleAppSamplesValidation(ITestOutputHelper output
         });
     }
 
-    [RetryFact(2, 5000)]
+    [RetryFact(2, 5000, Skip = "KeyNotFoundException in workflow execution. See https://github.com/microsoft/agent-framework/issues/6404")]
     public async Task WorkflowSharedStateSampleValidationAsync()
     {
         using CancellationTokenSource testTimeoutCts = this.CreateTestTimeoutCts(s_testTimeout);
@@ -376,7 +376,7 @@ public sealed class WorkflowConsoleAppSamplesValidation(ITestOutputHelper output
         });
     }
 
-    [RetryFact(2, 5000)]
+    [RetryFact(2, 5000, Skip = "KeyNotFoundException in workflow execution. See https://github.com/microsoft/agent-framework/issues/6404")]
     public async Task SubWorkflowsSampleValidationAsync()
     {
         using CancellationTokenSource testTimeoutCts = this.CreateTestTimeoutCts(s_testTimeout);
@@ -452,7 +452,7 @@ public sealed class WorkflowConsoleAppSamplesValidation(ITestOutputHelper output
         });
     }
 
-    [RetryFact(2, 5000)]
+    [RetryFact(2, 5000, Skip = "KeyNotFoundException in workflow execution. See https://github.com/microsoft/agent-framework/issues/6404")]
     public async Task WorkflowHITLSampleValidationAsync()
     {
         using CancellationTokenSource testTimeoutCts = this.CreateTestTimeoutCts(s_testTimeout);

dotnet/tests/Microsoft.Agents.AI.Foundry.Hosting.UnitTests/HostedFoundryMemoryProviderScopesTests.cs

@@ -43,7 +43,7 @@ public class HostedFoundryMemoryProviderScopesTests
     }
 
     [Fact]
-    public void PerUserAndChat_ComposesUserAndChatWithColon()
+    public void PerUserAndChat_ComposesUserAndChatWithEscapedSeparator()
     {
         // Arrange
         var session = CreateTaggedSession(TestUserId, TestChatId);
@@ -54,7 +54,51 @@ public class HostedFoundryMemoryProviderScopesTests
 
         // Assert
         Assert.NotNull(state);
-        Assert.Equal($"{TestUserId}:{TestChatId}", state.Scope.Scope);
+        Assert.Equal($"{TestUserId}::{TestChatId}", state.Scope.Scope);
+    }
+
+    [Fact]
+    public void PerUserAndChat_EscapesColonsInUserAndChat()
+    {
+        // Arrange
+        var session = CreateTaggedSession("alice:finance", "q2:final");
+        var initializer = HostedFoundryMemoryProviderScopes.PerUserAndChat();
+
+        // Act
+        var state = initializer(session);
+
+        // Assert - colons inside each part are escaped as \: , parts joined with ::
+        Assert.Equal(@"alice\:finance::q2\:final", state.Scope.Scope);
+    }
+
+    [Fact]
+    public void PerUserAndChat_EscapesBackslashesInUserAndChat()
+    {
+        // Arrange
+        var session = CreateTaggedSession(@"alice\corp", @"chat\1");
+        var initializer = HostedFoundryMemoryProviderScopes.PerUserAndChat();
+
+        // Act
+        var state = initializer(session);
+
+        // Assert - backslashes escaped first as \\ , parts joined with ::
+        Assert.Equal(@"alice\\corp::chat\\1", state.Scope.Scope);
+    }
+
+    [Fact]
+    public void PerUserAndChat_DistinctContextsDoNotCollide()
+    {
+        // Arrange - two distinct (UserId, ChatId) pairs that collide under raw-colon composition.
+        var sessionA = CreateTaggedSession("alice:finance", "q2");
+        var sessionB = CreateTaggedSession("alice", "finance:q2");
+        var initializer = HostedFoundryMemoryProviderScopes.PerUserAndChat();
+
+        // Act
+        var scopeA = initializer(sessionA).Scope.Scope;
+        var scopeB = initializer(sessionB).Scope.Scope;
+
+        // Assert
+        Assert.NotEqual(scopeA, scopeB);
     }
 
     [Fact]

dotnet/tests/Microsoft.Agents.AI.GitHub.Copilot.IntegrationTests/GitHubCopilotAgentTests.cs

@@ -4,7 +4,8 @@ using System;
 using System.Collections.Generic;
 using System.Linq;
 using System.Threading.Tasks;
-using GitHub.Copilot.SDK;
+using GitHub.Copilot;
+using GitHub.Copilot.Rpc;
 using Microsoft.Extensions.AI;
 
 namespace Microsoft.Agents.AI.GitHub.Copilot.IntegrationTests;
@@ -13,8 +14,8 @@ public class GitHubCopilotAgentTests
 {
     private const string SkipReason = "Integration tests require GitHub Copilot CLI installed. For local execution only.";
 
-    private static Task<PermissionRequestResult> OnPermissionRequestAsync(PermissionRequest request, PermissionInvocation invocation)
-        => Task.FromResult(new PermissionRequestResult { Kind = PermissionRequestResultKind.Approved });
+    private static Task<PermissionDecision> OnPermissionRequestAsync(PermissionRequest request, PermissionInvocation invocation)
+        => Task.FromResult(PermissionDecision.ApproveOnce());
 
     [Fact(Skip = SkipReason)]
     public async Task RunAsync_WithSimplePrompt_ReturnsResponseAsync()

dotnet/tests/Microsoft.Agents.AI.GitHub.Copilot.IntegrationTests/Microsoft.Agents.AI.GitHub.Copilot.IntegrationTests.csproj

@@ -3,6 +3,7 @@
   <PropertyGroup>
     <!-- GitHub.Copilot.SDK only supports .NET 8.0+ -->
     <TargetFrameworks>$(TargetFrameworksCore)</TargetFrameworks>
+    <NoWarn>$(NoWarn);GHCP001</NoWarn>
   </PropertyGroup>
 
   <ItemGroup>

dotnet/tests/Microsoft.Agents.AI.GitHub.Copilot.UnitTests/CopilotClientExtensionsTests.cs

@@ -2,7 +2,7 @@
 
 using System;
 using System.Collections.Generic;
-using GitHub.Copilot.SDK;
+using GitHub.Copilot;
 using Microsoft.Extensions.AI;
 
 namespace Microsoft.Agents.AI.GitHub.Copilot.UnitTests;
@@ -16,7 +16,7 @@ public sealed class CopilotClientExtensionsTests
     public void AsAIAgent_WithAllParameters_ReturnsGitHubCopilotAgentWithSpecifiedProperties()
     {
         // Arrange
-        CopilotClient copilotClient = new(new CopilotClientOptions { AutoStart = false });
+        CopilotClient copilotClient = new(new CopilotClientOptions());
 
         const string TestId = "test-agent-id";
         const string TestName = "Test Agent";
@@ -37,7 +37,7 @@ public sealed class CopilotClientExtensionsTests
     public void AsAIAgent_WithMinimalParameters_ReturnsGitHubCopilotAgent()
     {
         // Arrange
-        CopilotClient copilotClient = new(new CopilotClientOptions { AutoStart = false });
+        CopilotClient copilotClient = new(new CopilotClientOptions());
 
         // Act
         var agent = copilotClient.AsAIAgent(ownsClient: false, tools: null);
@@ -61,7 +61,7 @@ public sealed class CopilotClientExtensionsTests
     public void AsAIAgent_WithOwnsClient_ReturnsAgentThatOwnsClient()
     {
         // Arrange
-        CopilotClient copilotClient = new(new CopilotClientOptions { AutoStart = false });
+        CopilotClient copilotClient = new(new CopilotClientOptions());
 
         // Act
         var agent = copilotClient.AsAIAgent(ownsClient: true, tools: null);
@@ -75,7 +75,7 @@ public sealed class CopilotClientExtensionsTests
     public void AsAIAgent_WithTools_ReturnsAgentWithTools()
     {
         // Arrange
-        CopilotClient copilotClient = new(new CopilotClientOptions { AutoStart = false });
+        CopilotClient copilotClient = new(new CopilotClientOptions());
         List<AITool> tools = [AIFunctionFactory.Create(() => "test", "TestFunc", "Test function")];
 
         // Act

dotnet/tests/Microsoft.Agents.AI.GitHub.Copilot.UnitTests/GitHubCopilotAgentTests.cs

@@ -3,7 +3,8 @@
 using System;
 using System.Collections.Generic;
 using System.Threading.Tasks;
-using GitHub.Copilot.SDK;
+using GitHub.Copilot;
+using GitHub.Copilot.Rpc;
 using Microsoft.Extensions.AI;
 
 namespace Microsoft.Agents.AI.GitHub.Copilot.UnitTests;
@@ -17,7 +18,7 @@ public sealed class GitHubCopilotAgentTests
     public void Constructor_WithCopilotClient_InitializesPropertiesCorrectly()
     {
         // Arrange
-        CopilotClient copilotClient = new(new CopilotClientOptions { AutoStart = false });
+        CopilotClient copilotClient = new(new CopilotClientOptions());
         const string TestId = "test-id";
         const string TestName = "test-name";
         const string TestDescription = "test-description";
@@ -42,7 +43,7 @@ public sealed class GitHubCopilotAgentTests
     public void Constructor_WithDefaultParameters_UsesBaseProperties()
     {
         // Arrange
-        CopilotClient copilotClient = new(new CopilotClientOptions { AutoStart = false });
+        CopilotClient copilotClient = new(new CopilotClientOptions());
 
         // Act
         var agent = new GitHubCopilotAgent(copilotClient, ownsClient: false, tools: null);
@@ -58,7 +59,7 @@ public sealed class GitHubCopilotAgentTests
     public async Task CreateSessionAsync_ReturnsGitHubCopilotAgentSessionAsync()
     {
         // Arrange
-        CopilotClient copilotClient = new(new CopilotClientOptions { AutoStart = false });
+        CopilotClient copilotClient = new(new CopilotClientOptions());
         var agent = new GitHubCopilotAgent(copilotClient, ownsClient: false, tools: null);
 
         // Act
@@ -73,7 +74,7 @@ public sealed class GitHubCopilotAgentTests
     public async Task CreateSessionAsync_WithSessionId_ReturnsSessionWithSessionIdAsync()
     {
         // Arrange
-        CopilotClient copilotClient = new(new CopilotClientOptions { AutoStart = false });
+        CopilotClient copilotClient = new(new CopilotClientOptions());
         var agent = new GitHubCopilotAgent(copilotClient, ownsClient: false, tools: null);
         const string TestSessionId = "test-session-id";
 
@@ -90,7 +91,7 @@ public sealed class GitHubCopilotAgentTests
     public void Constructor_WithTools_InitializesCorrectly()
     {
         // Arrange
-        CopilotClient copilotClient = new(new CopilotClientOptions { AutoStart = false });
+        CopilotClient copilotClient = new(new CopilotClientOptions());
         List<AITool> tools = [AIFunctionFactory.Create(() => "test", "TestFunc", "Test function")];
 
         // Act
@@ -105,12 +106,12 @@ public sealed class GitHubCopilotAgentTests
     public void CopySessionConfig_CopiesAllProperties()
     {
         // Arrange
-        List<AIFunction> tools = [AIFunctionFactory.Create(() => "test", "TestFunc", "Test function")];
+        List<AIFunctionDeclaration> tools = [AIFunctionFactory.Create(() => "test", "TestFunc", "Test function")];
         var hooks = new SessionHooks();
         var infiniteSessions = new InfiniteSessionConfig();
         var systemMessage = new SystemMessageConfig { Mode = SystemMessageMode.Append, Content = "Be helpful" };
-        PermissionRequestHandler permissionHandler = (_, _) => Task.FromResult(new PermissionRequestResult());
-        UserInputHandler userInputHandler = (_, _) => Task.FromResult(new UserInputResponse { Answer = "input" });
+        Func<PermissionRequest, PermissionInvocation, Task<PermissionDecision>> permissionHandler = (_, _) => Task.FromResult(PermissionDecision.ApproveOnce());
+        Func<UserInputRequest, UserInputInvocation, Task<UserInputResponse>> userInputHandler = (_, _) => Task.FromResult(new UserInputResponse { Answer = "input" });
         var mcpServers = new Dictionary<string, McpServerConfig> { ["server1"] = new McpStdioServerConfig() };
 
         var source = new SessionConfig
@@ -122,7 +123,7 @@ public sealed class GitHubCopilotAgentTests
             AvailableTools = ["tool1", "tool2"],
             ExcludedTools = ["tool3"],
             WorkingDirectory = "/workspace",
-            ConfigDir = "/config",
+            ConfigDirectory = "/config",
             Hooks = hooks,
             InfiniteSessions = infiniteSessions,
             OnPermissionRequest = permissionHandler,
@@ -137,17 +138,15 @@ public sealed class GitHubCopilotAgentTests
         // Assert
         Assert.Equal("gpt-4o", result.Model);
         Assert.Equal("high", result.ReasoningEffort);
-        Assert.Same(tools, result.Tools);
-        Assert.Same(systemMessage, result.SystemMessage);
+        Assert.Equal(systemMessage, result.SystemMessage);
         Assert.Equal(new List<string> { "tool1", "tool2" }, result.AvailableTools);
         Assert.Equal(new List<string> { "tool3" }, result.ExcludedTools);
         Assert.Equal("/workspace", result.WorkingDirectory);
-        Assert.Equal("/config", result.ConfigDir);
+        Assert.Equal("/config", result.ConfigDirectory);
         Assert.Same(hooks, result.Hooks);
         Assert.Same(infiniteSessions, result.InfiniteSessions);
         Assert.Same(permissionHandler, result.OnPermissionRequest);
         Assert.Same(userInputHandler, result.OnUserInputRequest);
-        Assert.Same(mcpServers, result.McpServers);
         Assert.Equal(new List<string> { "skill1" }, result.DisabledSkills);
         Assert.True(result.Streaming);
     }
@@ -156,12 +155,12 @@ public sealed class GitHubCopilotAgentTests
     public void CopyResumeSessionConfig_CopiesAllProperties()
     {
         // Arrange
-        List<AIFunction> tools = [AIFunctionFactory.Create(() => "test", "TestFunc", "Test function")];
+        List<AIFunctionDeclaration> tools = [AIFunctionFactory.Create(() => "test", "TestFunc", "Test function")];
         var hooks = new SessionHooks();
         var infiniteSessions = new InfiniteSessionConfig();
         var systemMessage = new SystemMessageConfig { Mode = SystemMessageMode.Append, Content = "Be helpful" };
-        PermissionRequestHandler permissionHandler = (_, _) => Task.FromResult(new PermissionRequestResult());
-        UserInputHandler userInputHandler = (_, _) => Task.FromResult(new UserInputResponse { Answer = "input" });
+        Func<PermissionRequest, PermissionInvocation, Task<PermissionDecision>> permissionHandler = (_, _) => Task.FromResult(PermissionDecision.ApproveOnce());
+        Func<UserInputRequest, UserInputInvocation, Task<UserInputResponse>> userInputHandler = (_, _) => Task.FromResult(new UserInputResponse { Answer = "input" });
         var mcpServers = new Dictionary<string, McpServerConfig> { ["server1"] = new McpStdioServerConfig() };
 
         var source = new SessionConfig
@@ -173,7 +172,7 @@ public sealed class GitHubCopilotAgentTests
             AvailableTools = ["tool1", "tool2"],
             ExcludedTools = ["tool3"],
             WorkingDirectory = "/workspace",
-            ConfigDir = "/config",
+            ConfigDirectory = "/config",
             Hooks = hooks,
             InfiniteSessions = infiniteSessions,
             OnPermissionRequest = permissionHandler,
@@ -193,7 +192,7 @@ public sealed class GitHubCopilotAgentTests
         Assert.Equal(new List<string> { "tool1", "tool2" }, result.AvailableTools);
         Assert.Equal(new List<string> { "tool3" }, result.ExcludedTools);
         Assert.Equal("/workspace", result.WorkingDirectory);
-        Assert.Equal("/config", result.ConfigDir);
+        Assert.Equal("/config", result.ConfigDirectory);
         Assert.Same(hooks, result.Hooks);
         Assert.Same(infiniteSessions, result.InfiniteSessions);
         Assert.Same(permissionHandler, result.OnPermissionRequest);
@@ -218,7 +217,7 @@ public sealed class GitHubCopilotAgentTests
         Assert.Null(result.OnUserInputRequest);
         Assert.Null(result.Hooks);
         Assert.Null(result.WorkingDirectory);
-        Assert.Null(result.ConfigDir);
+        Assert.Null(result.ConfigDirectory);
         Assert.True(result.Streaming);
     }
 
@@ -233,7 +232,7 @@ public sealed class GitHubCopilotAgentTests
                 Content = "Some streamed content that was already delivered via delta events"
             }
         };
-        CopilotClient copilotClient = new(new CopilotClientOptions { AutoStart = false });
+        CopilotClient copilotClient = new(new CopilotClientOptions());
         const string TestId = "agent-id";
         var agent = new GitHubCopilotAgent(copilotClient, ownsClient: false, id: TestId, tools: null);
         AgentResponseUpdate result = agent.ConvertToAgentResponseUpdate(assistantMessage);

dotnet/tests/Microsoft.Agents.AI.GitHub.Copilot.UnitTests/Microsoft.Agents.AI.GitHub.Copilot.UnitTests.csproj

@@ -3,6 +3,7 @@
   <PropertyGroup>
     <!-- GitHub.Copilot.SDK only supports .NET 8.0+ -->
     <TargetFrameworks>$(TargetFrameworksCore)</TargetFrameworks>
+    <NoWarn>$(NoWarn);GHCP001</NoWarn>
   </PropertyGroup>
 
   <ItemGroup>

dotnet/tests/Microsoft.Agents.AI.Harness.UnitTests/HarnessAgentOptionsTests.cs

@@ -27,6 +27,7 @@ public class HarnessAgentOptionsTests
         Assert.Null(options.ChatHistoryProvider);
         Assert.Null(options.AIContextProviders);
         Assert.False(options.DisableToolApproval);
+        Assert.False(options.DisableNonApprovalRequiredFunctionBypassing);
         Assert.False(options.DisableFileMemory);
         Assert.False(options.DisableFileAccess);
         Assert.False(options.DisableWebSearch);
@@ -80,6 +81,7 @@ public class HarnessAgentOptionsTests
             AIContextProviders = contextProviders,
             MaximumIterationsPerRequest = 42,
             DisableToolApproval = true,
+            DisableNonApprovalRequiredFunctionBypassing = true,
             DisableFileMemory = true,
             FileMemoryStore = fileMemoryStore,
             DisableFileAccess = true,
@@ -112,6 +114,7 @@ public class HarnessAgentOptionsTests
         Assert.Same(contextProviders, options.AIContextProviders);
         Assert.Equal(42, options.MaximumIterationsPerRequest);
         Assert.True(options.DisableToolApproval);
+        Assert.True(options.DisableNonApprovalRequiredFunctionBypassing);
         Assert.True(options.DisableFileMemory);
         Assert.Same(fileMemoryStore, options.FileMemoryStore);
         Assert.True(options.DisableFileAccess);

dotnet/tests/Microsoft.Agents.AI.Harness.UnitTests/HarnessAgentTests.cs

@@ -21,9 +21,12 @@ public class HarnessAgentTests
 
     /// <summary>
     /// Creates a HarnessAgent with all default features disabled to isolate tests for specific behaviors.
+    /// Compaction is enabled by default for backward compatibility with existing tests.
     /// </summary>
     private static HarnessAgentOptions CreateAllDisabledOptions() => new()
     {
+        MaxContextWindowTokens = TestMaxContextWindowTokens,
+        MaxOutputTokens = TestMaxOutputTokens,
         DisableToolApproval = true,
         DisableOpenTelemetry = true,
         DisableFileMemory = true,
@@ -43,7 +46,7 @@ public class HarnessAgentTests
     public void Constructor_ThrowsWhenChatClientIsNull()
     {
         // Act & Assert
-        Assert.Throws<ArgumentNullException>(() => new HarnessAgent(null!, TestMaxContextWindowTokens, TestMaxOutputTokens));
+        Assert.Throws<ArgumentNullException>(() => new HarnessAgent(null!));
     }
 
     /// <summary>
@@ -54,9 +57,10 @@ public class HarnessAgentTests
     {
         // Arrange
         var chatClient = new Mock<IChatClient>().Object;
+        var options = new HarnessAgentOptions { MaxContextWindowTokens = 0, MaxOutputTokens = TestMaxOutputTokens };
 
         // Act & Assert
-        Assert.Throws<ArgumentOutOfRangeException>(() => new HarnessAgent(chatClient, 0, TestMaxOutputTokens));
+        Assert.Throws<ArgumentOutOfRangeException>(() => new HarnessAgent(chatClient, options));
     }
 
     /// <summary>
@@ -67,9 +71,10 @@ public class HarnessAgentTests
     {
         // Arrange
         var chatClient = new Mock<IChatClient>().Object;
+        var options = new HarnessAgentOptions { MaxContextWindowTokens = 100_000, MaxOutputTokens = 100_000 };
 
         // Act & Assert
-        Assert.Throws<ArgumentOutOfRangeException>(() => new HarnessAgent(chatClient, 100_000, 100_000));
+        Assert.Throws<ArgumentOutOfRangeException>(() => new HarnessAgent(chatClient, options));
     }
 
     /// <summary>
@@ -82,7 +87,7 @@ public class HarnessAgentTests
         var chatClient = new Mock<IChatClient>().Object;
 
         // Act
-        var agent = new HarnessAgent(chatClient, TestMaxContextWindowTokens, TestMaxOutputTokens);
+        var agent = new HarnessAgent(chatClient);
 
         // Assert
         Assert.NotNull(agent);
@@ -105,7 +110,7 @@ public class HarnessAgentTests
         options.Description = "A test agent";
 
         // Act
-        var agent = new HarnessAgent(chatClient, TestMaxContextWindowTokens, TestMaxOutputTokens, options);
+        var agent = new HarnessAgent(chatClient, options);
 
         // Assert
         Assert.Equal("TestAgent", agent.Name);
@@ -124,7 +129,7 @@ public class HarnessAgentTests
         options.Id = "my-agent-id";
 
         // Act
-        var agent = new HarnessAgent(chatClient, TestMaxContextWindowTokens, TestMaxOutputTokens, options);
+        var agent = new HarnessAgent(chatClient, options);
 
         // Assert
         Assert.Equal("my-agent-id", agent.Id);
@@ -144,7 +149,7 @@ public class HarnessAgentTests
         var chatClient = new Mock<IChatClient>().Object;
 
         // Act
-        var agent = new HarnessAgent(chatClient, TestMaxContextWindowTokens, TestMaxOutputTokens, CreateAllDisabledOptions());
+        var agent = new HarnessAgent(chatClient, CreateAllDisabledOptions());
         var innerAgent = agent.GetService<ChatClientAgent>();
 
         // Assert
@@ -164,7 +169,7 @@ public class HarnessAgentTests
         options.ChatOptions = new ChatOptions { Temperature = 0.5f };
 
         // Act
-        var agent = new HarnessAgent(chatClient, TestMaxContextWindowTokens, TestMaxOutputTokens, options);
+        var agent = new HarnessAgent(chatClient, options);
         var innerAgent = agent.GetService<ChatClientAgent>();
 
         // Assert
@@ -184,7 +189,7 @@ public class HarnessAgentTests
         options.ChatOptions = new ChatOptions { Instructions = "You are a custom assistant." };
 
         // Act
-        var agent = new HarnessAgent(chatClient, TestMaxContextWindowTokens, TestMaxOutputTokens, options);
+        var agent = new HarnessAgent(chatClient, options);
         var innerAgent = agent.GetService<ChatClientAgent>();
 
         // Assert
@@ -205,7 +210,7 @@ public class HarnessAgentTests
         options.HarnessInstructions = "Custom harness rules.";
 
         // Act
-        var agent = new HarnessAgent(chatClient, TestMaxContextWindowTokens, TestMaxOutputTokens, options);
+        var agent = new HarnessAgent(chatClient, options);
         var innerAgent = agent.GetService<ChatClientAgent>();
 
         // Assert
@@ -226,7 +231,7 @@ public class HarnessAgentTests
         options.ChatOptions = new ChatOptions { Instructions = "You are a research agent." };
 
         // Act
-        var agent = new HarnessAgent(chatClient, TestMaxContextWindowTokens, TestMaxOutputTokens, options);
+        var agent = new HarnessAgent(chatClient, options);
         var innerAgent = agent.GetService<ChatClientAgent>();
 
         // Assert
@@ -247,7 +252,7 @@ public class HarnessAgentTests
         options.ChatOptions = new ChatOptions { Instructions = "Agent only instructions." };
 
         // Act
-        var agent = new HarnessAgent(chatClient, TestMaxContextWindowTokens, TestMaxOutputTokens, options);
+        var agent = new HarnessAgent(chatClient, options);
         var innerAgent = agent.GetService<ChatClientAgent>();
 
         // Assert
@@ -267,7 +272,7 @@ public class HarnessAgentTests
         options.HarnessInstructions = string.Empty;
 
         // Act
-        var agent = new HarnessAgent(chatClient, TestMaxContextWindowTokens, TestMaxOutputTokens, options);
+        var agent = new HarnessAgent(chatClient, options);
         var innerAgent = agent.GetService<ChatClientAgent>();
 
         // Assert
@@ -289,7 +294,7 @@ public class HarnessAgentTests
         var chatClient = new Mock<IChatClient>().Object;
 
         // Act
-        var agent = new HarnessAgent(chatClient, TestMaxContextWindowTokens, TestMaxOutputTokens, CreateAllDisabledOptions());
+        var agent = new HarnessAgent(chatClient, CreateAllDisabledOptions());
         var innerAgent = agent.GetService<ChatClientAgent>();
 
         // Assert
@@ -310,7 +315,7 @@ public class HarnessAgentTests
         options.ChatHistoryProvider = customProvider;
 
         // Act
-        var agent = new HarnessAgent(chatClient, TestMaxContextWindowTokens, TestMaxOutputTokens, options);
+        var agent = new HarnessAgent(chatClient, options);
         var innerAgent = agent.GetService<ChatClientAgent>();
 
         // Assert
@@ -332,7 +337,7 @@ public class HarnessAgentTests
         var chatClient = new Mock<IChatClient>().Object;
 
         // Act
-        var agent = new HarnessAgent(chatClient, TestMaxContextWindowTokens, TestMaxOutputTokens, CreateAllDisabledOptions());
+        var agent = new HarnessAgent(chatClient, CreateAllDisabledOptions());
         var innerAgent = agent.GetService<ChatClientAgent>();
 
         // Assert
@@ -353,7 +358,7 @@ public class HarnessAgentTests
         var rawClient = mockClient.Object;
 
         // Act
-        var agent = new HarnessAgent(rawClient, TestMaxContextWindowTokens, TestMaxOutputTokens, CreateAllDisabledOptions());
+        var agent = new HarnessAgent(rawClient, CreateAllDisabledOptions());
         var innerAgent = agent.GetService<ChatClientAgent>();
 
         // Assert — the pipeline wraps the raw client, so the outer client is not the same object.
@@ -378,7 +383,7 @@ public class HarnessAgentTests
         options.AIContextProviders = [customProvider];
 
         // Act
-        var agent = new HarnessAgent(chatClient, TestMaxContextWindowTokens, TestMaxOutputTokens, options);
+        var agent = new HarnessAgent(chatClient, options);
         var innerAgent = agent.GetService<ChatClientAgent>();
 
         // Assert — the custom provider should appear in the inner agent's AIContextProviders.
@@ -398,7 +403,7 @@ public class HarnessAgentTests
         var chatClient = new Mock<IChatClient>().Object;
 
         // Act
-        var agent = new HarnessAgent(chatClient, TestMaxContextWindowTokens, TestMaxOutputTokens, CreateAllDisabledOptions());
+        var agent = new HarnessAgent(chatClient, CreateAllDisabledOptions());
         var innerAgent = agent.GetService<ChatClientAgent>();
 
         // Assert
@@ -432,7 +437,7 @@ public class HarnessAgentTests
         var options = CreateAllDisabledOptions();
         options.ChatOptions = new ChatOptions { Tools = [tool] };
 
-        var agent = new HarnessAgent(mockClient.Object, TestMaxContextWindowTokens, TestMaxOutputTokens, options);
+        var agent = new HarnessAgent(mockClient.Object, options);
         var session = await agent.CreateSessionAsync();
 
         // Act
@@ -459,8 +464,10 @@ public class HarnessAgentTests
         };
 
         // Act
-        _ = new HarnessAgent(chatClient, TestMaxContextWindowTokens, TestMaxOutputTokens, new HarnessAgentOptions
+        _ = new HarnessAgent(chatClient, new HarnessAgentOptions
         {
+            MaxContextWindowTokens = TestMaxContextWindowTokens,
+            MaxOutputTokens = TestMaxOutputTokens,
             ChatOptions = sourceChatOptions,
         });
 
@@ -483,7 +490,7 @@ public class HarnessAgentTests
         var chatClient = new Mock<IChatClient>().Object;
 
         // Act
-        var agent = new HarnessAgent(chatClient, TestMaxContextWindowTokens, TestMaxOutputTokens, CreateAllDisabledOptions());
+        var agent = new HarnessAgent(chatClient, CreateAllDisabledOptions());
 
         // Assert
         Assert.Same(agent, agent.GetService<HarnessAgent>());
@@ -499,7 +506,7 @@ public class HarnessAgentTests
         var chatClient = new Mock<IChatClient>().Object;
 
         // Act
-        var agent = new HarnessAgent(chatClient, TestMaxContextWindowTokens, TestMaxOutputTokens, CreateAllDisabledOptions());
+        var agent = new HarnessAgent(chatClient, CreateAllDisabledOptions());
 
         // Assert
         Assert.NotNull(agent.GetService<ChatClientAgent>());
@@ -524,7 +531,7 @@ public class HarnessAgentTests
                 It.IsAny<CancellationToken>()))
             .ReturnsAsync(new ChatResponse(new ChatMessage(ChatRole.Assistant, "Hello!")));
 
-        var agent = new HarnessAgent(mockClient.Object, TestMaxContextWindowTokens, TestMaxOutputTokens, CreateAllDisabledOptions());
+        var agent = new HarnessAgent(mockClient.Object, CreateAllDisabledOptions());
         var session = await agent.CreateSessionAsync();
 
         // Act
@@ -565,7 +572,7 @@ public class HarnessAgentTests
         var chatClient = new Mock<IChatClient>().Object;
 
         // Act
-        var agent = chatClient.AsHarnessAgent(TestMaxContextWindowTokens, TestMaxOutputTokens);
+        var agent = chatClient.AsHarnessAgent();
 
         // Assert
         Assert.NotNull(agent);
@@ -586,7 +593,7 @@ public class HarnessAgentTests
         options.ChatOptions = new ChatOptions { Instructions = "Custom instructions" };
 
         // Act
-        var agent = chatClient.AsHarnessAgent(TestMaxContextWindowTokens, TestMaxOutputTokens, options);
+        var agent = chatClient.AsHarnessAgent(options);
         var innerAgent = agent.GetService<ChatClientAgent>();
 
         // Assert
@@ -603,7 +610,7 @@ public class HarnessAgentTests
     public void AsHarnessAgent_ThrowsWhenChatClientIsNull()
     {
         // Act & Assert
-        Assert.Throws<ArgumentNullException>(() => ((IChatClient)null!).AsHarnessAgent(TestMaxContextWindowTokens, TestMaxOutputTokens));
+        Assert.Throws<ArgumentNullException>(() => ((IChatClient)null!).AsHarnessAgent());
     }
 
     #endregion
@@ -622,7 +629,7 @@ public class HarnessAgentTests
         options.DisableToolApproval = false;
 
         // Act
-        var agent = new HarnessAgent(chatClient, TestMaxContextWindowTokens, TestMaxOutputTokens, options);
+        var agent = new HarnessAgent(chatClient, options);
 
         // Assert
         Assert.NotNull(agent.GetService<ToolApprovalAgent>());
@@ -638,7 +645,7 @@ public class HarnessAgentTests
         var chatClient = new Mock<IChatClient>().Object;
 
         // Act
-        var agent = new HarnessAgent(chatClient, TestMaxContextWindowTokens, TestMaxOutputTokens, CreateAllDisabledOptions());
+        var agent = new HarnessAgent(chatClient, CreateAllDisabledOptions());
 
         // Assert
         Assert.Null(agent.GetService<ToolApprovalAgent>());
@@ -678,7 +685,7 @@ public class HarnessAgentTests
             AutoApprovalRules = [fcc => new ValueTask<bool>(fcc.Name == "ReadTool")]
         };
 
-        var agent = new HarnessAgent(mockClient.Object, TestMaxContextWindowTokens, TestMaxOutputTokens, options);
+        var agent = new HarnessAgent(mockClient.Object, options);
         var session = await agent.CreateSessionAsync();
 
         // Act
@@ -691,6 +698,97 @@ public class HarnessAgentTests
 
     #endregion
 
+    #region Feature: NonApprovalRequiredFunctionBypassing
+
+    /// <summary>
+    /// Verify that by default, when a response contains a mix of tools that require approval and tools that do not,
+    /// only the approval-required tool is surfaced to the caller. The non-approval-required tool is bypassed
+    /// (stored as auto-approved) by the <c>NonApprovalRequiredFunctionBypassingChatClient</c> decorator.
+    /// </summary>
+    [Fact]
+    public async Task NonApprovalRequiredFunctionBypassing_BypassesNonApprovalToolsByDefaultAsync()
+    {
+        // Arrange — the model requests both a normal tool and an approval-required tool in the same turn.
+        var normalTool = AIFunctionFactory.Create(() => "result", "NormalTool");
+        var approvalTool = new ApprovalRequiredAIFunction(AIFunctionFactory.Create(() => "result", "ApprovalTool"));
+
+        var mockClient = new Mock<IChatClient>();
+        mockClient
+            .Setup(c => c.GetResponseAsync(
+                It.IsAny<IEnumerable<ChatMessage>>(),
+                It.IsAny<ChatOptions>(),
+                It.IsAny<CancellationToken>()))
+            .ReturnsAsync(() => new ChatResponse(new ChatMessage(ChatRole.Assistant,
+            [
+                new FunctionCallContent("call1", "NormalTool"),
+                new FunctionCallContent("call2", "ApprovalTool"),
+            ])));
+
+        // Disable ToolApproval so the approval requests surface in the response instead of being handled.
+        var options = CreateAllDisabledOptions();
+        options.ChatOptions = new ChatOptions { Tools = [normalTool, approvalTool] };
+
+        var agent = new HarnessAgent(mockClient.Object, options);
+        var session = await agent.CreateSessionAsync();
+
+        // Act
+        var response = await agent.RunAsync([new ChatMessage(ChatRole.User, "Hi")], session);
+
+        // Assert — only the approval-required tool surfaces as an approval request; the normal tool is bypassed.
+        var approvalRequests = response.Messages
+            .SelectMany(m => m.Contents)
+            .OfType<ToolApprovalRequestContent>()
+            .ToList();
+        var approvalRequest = Assert.Single(approvalRequests);
+        Assert.Equal("ApprovalTool", Assert.IsType<FunctionCallContent>(approvalRequest.ToolCall).Name);
+    }
+
+    /// <summary>
+    /// Verify that when bypassing is disabled, all tools (including those that do not require approval) are surfaced
+    /// as approval requests, reflecting the all-or-nothing behavior of <see cref="FunctionInvokingChatClient"/>.
+    /// </summary>
+    [Fact]
+    public async Task NonApprovalRequiredFunctionBypassing_SurfacesAllApprovalsWhenDisabledAsync()
+    {
+        // Arrange — the model requests both a normal tool and an approval-required tool in the same turn.
+        var normalTool = AIFunctionFactory.Create(() => "result", "NormalTool");
+        var approvalTool = new ApprovalRequiredAIFunction(AIFunctionFactory.Create(() => "result", "ApprovalTool"));
+
+        var mockClient = new Mock<IChatClient>();
+        mockClient
+            .Setup(c => c.GetResponseAsync(
+                It.IsAny<IEnumerable<ChatMessage>>(),
+                It.IsAny<ChatOptions>(),
+                It.IsAny<CancellationToken>()))
+            .ReturnsAsync(() => new ChatResponse(new ChatMessage(ChatRole.Assistant,
+            [
+                new FunctionCallContent("call1", "NormalTool"),
+                new FunctionCallContent("call2", "ApprovalTool"),
+            ])));
+
+        var options = CreateAllDisabledOptions();
+        options.DisableNonApprovalRequiredFunctionBypassing = true;
+        options.ChatOptions = new ChatOptions { Tools = [normalTool, approvalTool] };
+
+        var agent = new HarnessAgent(mockClient.Object, options);
+        var session = await agent.CreateSessionAsync();
+
+        // Act
+        var response = await agent.RunAsync([new ChatMessage(ChatRole.User, "Hi")], session);
+
+        // Assert — both tools surface as approval requests because bypassing is disabled.
+        var approvalRequests = response.Messages
+            .SelectMany(m => m.Contents)
+            .OfType<ToolApprovalRequestContent>()
+            .Select(r => ((FunctionCallContent)r.ToolCall).Name)
+            .ToList();
+        Assert.Equal(2, approvalRequests.Count);
+        Assert.Contains("NormalTool", approvalRequests);
+        Assert.Contains("ApprovalTool", approvalRequests);
+    }
+
+    #endregion
+
     #region Feature: OpenTelemetry
 
     /// <summary>
@@ -705,7 +803,7 @@ public class HarnessAgentTests
         options.DisableOpenTelemetry = false;
 
         // Act
-        var agent = new HarnessAgent(chatClient, TestMaxContextWindowTokens, TestMaxOutputTokens, options);
+        var agent = new HarnessAgent(chatClient, options);
 
         // Assert
         Assert.NotNull(agent.GetService<OpenTelemetryAgent>());
@@ -721,7 +819,7 @@ public class HarnessAgentTests
         var chatClient = new Mock<IChatClient>().Object;
 
         // Act
-        var agent = new HarnessAgent(chatClient, TestMaxContextWindowTokens, TestMaxOutputTokens, CreateAllDisabledOptions());
+        var agent = new HarnessAgent(chatClient, CreateAllDisabledOptions());
 
         // Assert
         Assert.Null(agent.GetService<OpenTelemetryAgent>());
@@ -740,7 +838,7 @@ public class HarnessAgentTests
         options.OpenTelemetrySourceName = "MyApp.AgentTracing";
 
         // Act
-        var agent = new HarnessAgent(chatClient, TestMaxContextWindowTokens, TestMaxOutputTokens, options);
+        var agent = new HarnessAgent(chatClient, options);
 
         // Assert
         Assert.NotNull(agent.GetService<OpenTelemetryAgent>());
@@ -767,7 +865,7 @@ public class HarnessAgentTests
         var options = CreateAllDisabledOptions();
         options.DisableWebSearch = false;
 
-        var agent = new HarnessAgent(mockClient.Object, TestMaxContextWindowTokens, TestMaxOutputTokens, options);
+        var agent = new HarnessAgent(mockClient.Object, options);
         var session = await agent.CreateSessionAsync();
 
         // Act
@@ -792,7 +890,7 @@ public class HarnessAgentTests
             .Callback<IEnumerable<ChatMessage>, ChatOptions?, CancellationToken>((_, opts, _) => capturedOptions = opts)
             .ReturnsAsync(new ChatResponse(new ChatMessage(ChatRole.Assistant, "Done")));
 
-        var agent = new HarnessAgent(mockClient.Object, TestMaxContextWindowTokens, TestMaxOutputTokens, CreateAllDisabledOptions());
+        var agent = new HarnessAgent(mockClient.Object, CreateAllDisabledOptions());
         var session = await agent.CreateSessionAsync();
 
         // Act
@@ -825,7 +923,7 @@ public class HarnessAgentTests
         options.DisableWebSearch = false;
         options.ChatOptions = new ChatOptions { Tools = [userTool] };
 
-        var agent = new HarnessAgent(mockClient.Object, TestMaxContextWindowTokens, TestMaxOutputTokens, options);
+        var agent = new HarnessAgent(mockClient.Object, options);
         var session = await agent.CreateSessionAsync();
 
         // Act
@@ -853,7 +951,7 @@ public class HarnessAgentTests
         options.DisableTodoProvider = false;
 
         // Act
-        var agent = new HarnessAgent(chatClient, TestMaxContextWindowTokens, TestMaxOutputTokens, options);
+        var agent = new HarnessAgent(chatClient, options);
         var innerAgent = agent.GetService<ChatClientAgent>();
 
         // Assert
@@ -871,7 +969,7 @@ public class HarnessAgentTests
         var chatClient = new Mock<IChatClient>().Object;
 
         // Act
-        var agent = new HarnessAgent(chatClient, TestMaxContextWindowTokens, TestMaxOutputTokens, CreateAllDisabledOptions());
+        var agent = new HarnessAgent(chatClient, CreateAllDisabledOptions());
         var innerAgent = agent.GetService<ChatClientAgent>();
 
         // Assert
@@ -898,7 +996,7 @@ public class HarnessAgentTests
         options.DisableAgentModeProvider = false;
 
         // Act
-        var agent = new HarnessAgent(chatClient, TestMaxContextWindowTokens, TestMaxOutputTokens, options);
+        var agent = new HarnessAgent(chatClient, options);
         var innerAgent = agent.GetService<ChatClientAgent>();
 
         // Assert
@@ -916,7 +1014,7 @@ public class HarnessAgentTests
         var chatClient = new Mock<IChatClient>().Object;
 
         // Act
-        var agent = new HarnessAgent(chatClient, TestMaxContextWindowTokens, TestMaxOutputTokens, CreateAllDisabledOptions());
+        var agent = new HarnessAgent(chatClient, CreateAllDisabledOptions());
         var innerAgent = agent.GetService<ChatClientAgent>();
 
         // Assert
@@ -947,7 +1045,7 @@ public class HarnessAgentTests
         };
 
         // Act
-        var agent = new HarnessAgent(chatClient, TestMaxContextWindowTokens, TestMaxOutputTokens, options);
+        var agent = new HarnessAgent(chatClient, options);
         var innerAgent = agent.GetService<ChatClientAgent>();
 
         // Assert — AgentModeProvider should be present (we can't easily inspect its internal options,
@@ -972,7 +1070,7 @@ public class HarnessAgentTests
         options.DisableFileMemory = false;
 
         // Act
-        var agent = new HarnessAgent(chatClient, TestMaxContextWindowTokens, TestMaxOutputTokens, options);
+        var agent = new HarnessAgent(chatClient, options);
         var innerAgent = agent.GetService<ChatClientAgent>();
 
         // Assert
@@ -990,7 +1088,7 @@ public class HarnessAgentTests
         var chatClient = new Mock<IChatClient>().Object;
 
         // Act
-        var agent = new HarnessAgent(chatClient, TestMaxContextWindowTokens, TestMaxOutputTokens, CreateAllDisabledOptions());
+        var agent = new HarnessAgent(chatClient, CreateAllDisabledOptions());
         var innerAgent = agent.GetService<ChatClientAgent>();
 
         // Assert
@@ -1015,7 +1113,7 @@ public class HarnessAgentTests
         options.FileMemoryStore = customStore;
 
         // Act
-        var agent = new HarnessAgent(chatClient, TestMaxContextWindowTokens, TestMaxOutputTokens, options);
+        var agent = new HarnessAgent(chatClient, options);
         var innerAgent = agent.GetService<ChatClientAgent>();
 
         // Assert — FileMemoryProvider should be present with the custom store.
@@ -1039,7 +1137,7 @@ public class HarnessAgentTests
         options.DisableFileAccess = false;
 
         // Act
-        var agent = new HarnessAgent(chatClient, TestMaxContextWindowTokens, TestMaxOutputTokens, options);
+        var agent = new HarnessAgent(chatClient, options);
         var innerAgent = agent.GetService<ChatClientAgent>();
 
         // Assert
@@ -1057,7 +1155,7 @@ public class HarnessAgentTests
         var chatClient = new Mock<IChatClient>().Object;
 
         // Act
-        var agent = new HarnessAgent(chatClient, TestMaxContextWindowTokens, TestMaxOutputTokens, CreateAllDisabledOptions());
+        var agent = new HarnessAgent(chatClient, CreateAllDisabledOptions());
         var innerAgent = agent.GetService<ChatClientAgent>();
 
         // Assert
@@ -1082,7 +1180,7 @@ public class HarnessAgentTests
         options.FileAccessStore = customStore;
 
         // Act
-        var agent = new HarnessAgent(chatClient, TestMaxContextWindowTokens, TestMaxOutputTokens, options);
+        var agent = new HarnessAgent(chatClient, options);
         var innerAgent = agent.GetService<ChatClientAgent>();
 
         // Assert — FileAccessProvider should be present with the custom store.
@@ -1106,7 +1204,7 @@ public class HarnessAgentTests
         options.DisableAgentSkillsProvider = false;
 
         // Act
-        var agent = new HarnessAgent(chatClient, TestMaxContextWindowTokens, TestMaxOutputTokens, options);
+        var agent = new HarnessAgent(chatClient, options);
         var innerAgent = agent.GetService<ChatClientAgent>();
 
         // Assert
@@ -1124,7 +1222,7 @@ public class HarnessAgentTests
         var chatClient = new Mock<IChatClient>().Object;
 
         // Act
-        var agent = new HarnessAgent(chatClient, TestMaxContextWindowTokens, TestMaxOutputTokens, CreateAllDisabledOptions());
+        var agent = new HarnessAgent(chatClient, CreateAllDisabledOptions());
         var innerAgent = agent.GetService<ChatClientAgent>();
 
         // Assert
@@ -1149,7 +1247,7 @@ public class HarnessAgentTests
         options.AgentSkillsSource = customSource;
 
         // Act
-        var agent = new HarnessAgent(chatClient, TestMaxContextWindowTokens, TestMaxOutputTokens, options);
+        var agent = new HarnessAgent(chatClient, options);
         var innerAgent = agent.GetService<ChatClientAgent>();
 
         // Assert — AgentSkillsProvider should be present.
@@ -1173,7 +1271,7 @@ public class HarnessAgentTests
         options.MaximumIterationsPerRequest = 42;
 
         // Act
-        var agent = new HarnessAgent(chatClient, TestMaxContextWindowTokens, TestMaxOutputTokens, options);
+        var agent = new HarnessAgent(chatClient, options);
         var innerAgent = agent.GetService<ChatClientAgent>();
         var ficc = innerAgent!.ChatClient.GetService<FunctionInvokingChatClient>();
 
@@ -1192,7 +1290,7 @@ public class HarnessAgentTests
         var chatClient = new Mock<IChatClient>().Object;
 
         // Act
-        var agent = new HarnessAgent(chatClient, TestMaxContextWindowTokens, TestMaxOutputTokens, CreateAllDisabledOptions());
+        var agent = new HarnessAgent(chatClient, CreateAllDisabledOptions());
         var innerAgent = agent.GetService<ChatClientAgent>();
         var ficc = innerAgent!.ChatClient.GetService<FunctionInvokingChatClient>();
 
@@ -1220,7 +1318,7 @@ public class HarnessAgentTests
             .ReturnsAsync(new ChatResponse(new ChatMessage(ChatRole.Assistant, "Done")));
 
         // Act
-        var agent = new HarnessAgent(mockClient.Object, TestMaxContextWindowTokens, TestMaxOutputTokens);
+        var agent = new HarnessAgent(mockClient.Object);
         var innerAgent = agent.GetService<ChatClientAgent>();
 
         // Assert — agent wrappers
@@ -1263,7 +1361,7 @@ public class HarnessAgentTests
         options.BackgroundAgents = [bgAgentMock.Object];
 
         // Act
-        var agent = new HarnessAgent(chatClient, TestMaxContextWindowTokens, TestMaxOutputTokens, options);
+        var agent = new HarnessAgent(chatClient, options);
         var innerAgent = agent.GetService<ChatClientAgent>();
 
         // Assert
@@ -1283,7 +1381,7 @@ public class HarnessAgentTests
         options.BackgroundAgents = null;
 
         // Act
-        var agent = new HarnessAgent(chatClient, TestMaxContextWindowTokens, TestMaxOutputTokens, options);
+        var agent = new HarnessAgent(chatClient, options);
         var innerAgent = agent.GetService<ChatClientAgent>();
 
         // Assert
@@ -1306,7 +1404,7 @@ public class HarnessAgentTests
         options.BackgroundAgents = Array.Empty<AIAgent>();
 
         // Act
-        var agent = new HarnessAgent(chatClient, TestMaxContextWindowTokens, TestMaxOutputTokens, options);
+        var agent = new HarnessAgent(chatClient, options);
         var innerAgent = agent.GetService<ChatClientAgent>();
 
         // Assert
@@ -1337,7 +1435,7 @@ public class HarnessAgentTests
         options.BackgroundAgentsProviderOptions = providerOptions;
 
         // Act
-        var agent = new HarnessAgent(chatClient, TestMaxContextWindowTokens, TestMaxOutputTokens, options);
+        var agent = new HarnessAgent(chatClient, options);
         var innerAgent = agent.GetService<ChatClientAgent>();
         var bgProvider = innerAgent!.AIContextProviders!.OfType<BackgroundAgentsProvider>().Single();
 
@@ -1374,7 +1472,7 @@ public class HarnessAgentTests
         options.BackgroundAgents = [agent1Mock.Object, agent2Mock.Object];
 
         // Act
-        var agent = new HarnessAgent(chatClient, TestMaxContextWindowTokens, TestMaxOutputTokens, options);
+        var agent = new HarnessAgent(chatClient, options);
         var innerAgent = agent.GetService<ChatClientAgent>();
         var bgProvider = innerAgent!.AIContextProviders!.OfType<BackgroundAgentsProvider>().Single();
 
@@ -1415,7 +1513,7 @@ public class HarnessAgentTests
         options.ShellExecutor = executorMock.Object;
 
         // Act
-        var agent = new HarnessAgent(chatClient, TestMaxContextWindowTokens, TestMaxOutputTokens, options);
+        var agent = new HarnessAgent(chatClient, options);
         var innerAgent = agent.GetService<ChatClientAgent>();
 
         // Assert
@@ -1435,7 +1533,7 @@ public class HarnessAgentTests
         options.ShellExecutor = null;
 
         // Act
-        var agent = new HarnessAgent(chatClient, TestMaxContextWindowTokens, TestMaxOutputTokens, options);
+        var agent = new HarnessAgent(chatClient, options);
         var innerAgent = agent.GetService<ChatClientAgent>();
 
         // Assert
@@ -1467,7 +1565,7 @@ public class HarnessAgentTests
         options.ShellExecutor = executorMock.Object;
 
         // Act
-        var agent = new HarnessAgent(chatClientMock.Object, TestMaxContextWindowTokens, TestMaxOutputTokens, options);
+        var agent = new HarnessAgent(chatClientMock.Object, options);
         var session = await agent.CreateSessionAsync();
         await agent.RunAsync([new ChatMessage(ChatRole.User, "Hi")], session);
 
@@ -1496,7 +1594,7 @@ public class HarnessAgentTests
         options.ShellEnvironmentProviderOptions = envOptions;
 
         // Act
-        var agent = new HarnessAgent(chatClient, TestMaxContextWindowTokens, TestMaxOutputTokens, options);
+        var agent = new HarnessAgent(chatClient, options);
         var innerAgent = agent.GetService<ChatClientAgent>();
 
         // Assert — provider should exist (options wiring is validated by the provider's behavior)
@@ -1520,7 +1618,7 @@ public class HarnessAgentTests
         var loggerFactory = new Mock<ILoggerFactory>().Object;
 
         // Act
-        var agent = new HarnessAgent(chatClient, TestMaxContextWindowTokens, TestMaxOutputTokens, CreateAllDisabledOptions(), loggerFactory);
+        var agent = new HarnessAgent(chatClient, CreateAllDisabledOptions(), loggerFactory);
 
         // Assert
         Assert.NotNull(agent);
@@ -1537,7 +1635,7 @@ public class HarnessAgentTests
         var services = new Mock<IServiceProvider>().Object;
 
         // Act
-        var agent = new HarnessAgent(chatClient, TestMaxContextWindowTokens, TestMaxOutputTokens, CreateAllDisabledOptions(), services: services);
+        var agent = new HarnessAgent(chatClient, CreateAllDisabledOptions(), services: services);
 
         // Assert
         Assert.NotNull(agent);
@@ -1555,7 +1653,7 @@ public class HarnessAgentTests
         var services = new Mock<IServiceProvider>().Object;
 
         // Act
-        var agent = new HarnessAgent(chatClient, TestMaxContextWindowTokens, TestMaxOutputTokens, CreateAllDisabledOptions(), loggerFactory, services);
+        var agent = new HarnessAgent(chatClient, CreateAllDisabledOptions(), loggerFactory, services);
 
         // Assert
         Assert.NotNull(agent);
@@ -1573,7 +1671,7 @@ public class HarnessAgentTests
         var services = new Mock<IServiceProvider>().Object;
 
         // Act
-        var agent = chatClient.AsHarnessAgent(TestMaxContextWindowTokens, TestMaxOutputTokens, CreateAllDisabledOptions(), loggerFactory, services);
+        var agent = chatClient.AsHarnessAgent(CreateAllDisabledOptions(), loggerFactory, services);
 
         // Assert
         Assert.NotNull(agent);
@@ -1595,6 +1693,8 @@ public class HarnessAgentTests
         // Act — use options that leave CompactionProvider and AgentSkillsProvider enabled
         var options = new HarnessAgentOptions
         {
+            MaxContextWindowTokens = TestMaxContextWindowTokens,
+            MaxOutputTokens = TestMaxOutputTokens,
             DisableToolApproval = true,
             DisableOpenTelemetry = true,
             DisableFileMemory = true,
@@ -1603,7 +1703,7 @@ public class HarnessAgentTests
             DisableTodoProvider = true,
             DisableAgentModeProvider = true,
         };
-        var agent = new HarnessAgent(chatClient, TestMaxContextWindowTokens, TestMaxOutputTokens, options, mockLoggerFactory.Object);
+        var agent = new HarnessAgent(chatClient, options, mockLoggerFactory.Object);
 
         // Assert — CreateLogger should have been called by one or more downstream components
         Assert.NotNull(agent);
@@ -1625,7 +1725,7 @@ public class HarnessAgentTests
             .Returns(null!);
 
         // Act
-        var agent = new HarnessAgent(chatClient, TestMaxContextWindowTokens, TestMaxOutputTokens, CreateAllDisabledOptions(), services: mockServices.Object);
+        var agent = new HarnessAgent(chatClient, CreateAllDisabledOptions(), services: mockServices.Object);
 
         // Assert — the service provider should have been queried during pipeline construction
         Assert.NotNull(agent);
@@ -1633,4 +1733,91 @@ public class HarnessAgentTests
     }
 
     #endregion
+
+    #region Compaction Opt-in
+
+    /// <summary>
+    /// Verify that constructing without token values succeeds (compaction disabled).
+    /// </summary>
+    [Fact]
+    public void Constructor_SucceedsWithoutTokenValues()
+    {
+        // Arrange
+        var chatClient = new Mock<IChatClient>().Object;
+        var options = new HarnessAgentOptions
+        {
+            DisableToolApproval = true,
+            DisableOpenTelemetry = true,
+            DisableFileMemory = true,
+            DisableFileAccess = true,
+            DisableWebSearch = true,
+            DisableTodoProvider = true,
+            DisableAgentModeProvider = true,
+            DisableAgentSkillsProvider = true,
+        };
+
+        // Act
+        var agent = new HarnessAgent(chatClient, options);
+
+        // Assert — compaction should be disabled (no chat reducer)
+        var innerAgent = agent.GetService<ChatClientAgent>();
+        Assert.NotNull(innerAgent);
+        var historyProvider = innerAgent!.ChatHistoryProvider as InMemoryChatHistoryProvider;
+        Assert.NotNull(historyProvider);
+        Assert.Null(historyProvider!.ChatReducer);
+    }
+
+    /// <summary>
+    /// Verify that when only MaxContextWindowTokens is provided (no MaxOutputTokens), compaction is disabled.
+    /// </summary>
+    [Fact]
+    public void Constructor_SucceedsWithOnlyMaxContextWindowTokens()
+    {
+        // Arrange
+        var chatClient = new Mock<IChatClient>().Object;
+        var options = new HarnessAgentOptions
+        {
+            MaxContextWindowTokens = TestMaxContextWindowTokens,
+            DisableToolApproval = true,
+            DisableOpenTelemetry = true,
+            DisableFileMemory = true,
+            DisableFileAccess = true,
+            DisableWebSearch = true,
+            DisableTodoProvider = true,
+            DisableAgentModeProvider = true,
+            DisableAgentSkillsProvider = true,
+        };
+
+        // Act
+        var agent = new HarnessAgent(chatClient, options);
+
+        // Assert — compaction should be disabled (only one token value provided)
+        var innerAgent = agent.GetService<ChatClientAgent>();
+        Assert.NotNull(innerAgent);
+        var historyProvider = innerAgent!.ChatHistoryProvider as InMemoryChatHistoryProvider;
+        Assert.NotNull(historyProvider);
+        Assert.Null(historyProvider!.ChatReducer);
+    }
+
+    /// <summary>
+    /// Verify that when both token values are provided, the agent is constructed successfully with compaction.
+    /// </summary>
+    [Fact]
+    public void Constructor_SucceedsWithBothTokenValues()
+    {
+        // Arrange
+        var chatClient = new Mock<IChatClient>().Object;
+
+        // Act
+        var agent = new HarnessAgent(chatClient, CreateAllDisabledOptions());
+
+        // Assert — compaction should be enabled (chat reducer configured)
+        var innerAgent = agent.GetService<ChatClientAgent>();
+        Assert.NotNull(innerAgent);
+        var historyProvider = innerAgent!.ChatHistoryProvider as InMemoryChatHistoryProvider;
+        Assert.NotNull(historyProvider);
+        Assert.NotNull(historyProvider!.ChatReducer);
+    }
+
+    #endregion
 }

dotnet/tests/Microsoft.Agents.AI.Hosting.AzureFunctions.IntegrationTests/SamplesValidation.cs

@@ -60,7 +60,7 @@ public sealed class SamplesValidation(ITestOutputHelper outputHelper) : IAsyncLi
         await Task.CompletedTask;
     }
 
-    [RetryFact(2, 5000)]
+    [RetryFact(2, 5000, Skip = "Azure Functions Core Tools v4 cannot auto-detect worker runtime in CI. See https://github.com/microsoft/agent-framework/issues/6402")]
     public async Task SingleAgentSampleValidationAsync()
     {
         string samplePath = Path.Combine(s_samplesPath, "01_SingleAgent");
@@ -148,7 +148,7 @@ public sealed class SamplesValidation(ITestOutputHelper outputHelper) : IAsyncLi
         });
     }
 
-    [RetryFact(2, 5000)]
+    [RetryFact(2, 5000, Skip = "Azure Functions Core Tools v4 cannot auto-detect worker runtime in CI. See https://github.com/microsoft/agent-framework/issues/6402")]
     public async Task MultiAgentOrchestrationConcurrentSampleValidationAsync()
     {
         string samplePath = Path.Combine(s_samplesPath, "03_AgentOrchestration_Concurrency");
@@ -198,7 +198,7 @@ public sealed class SamplesValidation(ITestOutputHelper outputHelper) : IAsyncLi
         });
     }
 
-    [RetryFact(2, 5000)]
+    [RetryFact(2, 5000, Skip = "Azure Functions Core Tools v4 cannot auto-detect worker runtime in CI. See https://github.com/microsoft/agent-framework/issues/6402")]
     public async Task MultiAgentOrchestrationConditionalsSampleValidationAsync()
     {
         string samplePath = Path.Combine(s_samplesPath, "04_AgentOrchestration_Conditionals");
@@ -216,7 +216,7 @@ public sealed class SamplesValidation(ITestOutputHelper outputHelper) : IAsyncLi
         });
     }
 
-    [RetryFact(2, 5000)]
+    [RetryFact(2, 5000, Skip = "Azure Functions Core Tools v4 cannot auto-detect worker runtime in CI. See https://github.com/microsoft/agent-framework/issues/6402")]
     public async Task SingleAgentOrchestrationHITLSampleValidationAsync()
     {
         string samplePath = Path.Combine(s_samplesPath, "05_AgentOrchestration_HITL");
@@ -272,7 +272,7 @@ public sealed class SamplesValidation(ITestOutputHelper outputHelper) : IAsyncLi
         });
     }
 
-    [RetryFact(2, 5000)]
+    [RetryFact(2, 5000, Skip = "Azure Functions Core Tools v4 cannot auto-detect worker runtime in CI. See https://github.com/microsoft/agent-framework/issues/6402")]
     public async Task LongRunningToolsSampleValidationAsync()
     {
         string samplePath = Path.Combine(s_samplesPath, "06_LongRunningTools");
@@ -362,7 +362,7 @@ public sealed class SamplesValidation(ITestOutputHelper outputHelper) : IAsyncLi
         });
     }
 
-    [RetryFact(2, 5000)]
+    [RetryFact(2, 5000, Skip = "Azure Functions Core Tools v4 cannot auto-detect worker runtime in CI. See https://github.com/microsoft/agent-framework/issues/6402")]
     public async Task AgentAsMcpToolAsync()
     {
         string samplePath = Path.Combine(s_samplesPath, "07_AgentAsMcpTool");
@@ -402,7 +402,7 @@ public sealed class SamplesValidation(ITestOutputHelper outputHelper) : IAsyncLi
         });
     }
 
-    [RetryFact(2, 5000)]
+    [RetryFact(2, 5000, Skip = "Azure Functions Core Tools v4 cannot auto-detect worker runtime in CI. See https://github.com/microsoft/agent-framework/issues/6402")]
     public async Task ReliableStreamingSampleValidationAsync()
     {
         string samplePath = Path.Combine(s_samplesPath, "08_ReliableStreaming");

dotnet/tests/Microsoft.Agents.AI.Hosting.AzureFunctions.IntegrationTests/WorkflowSamplesValidation.cs

@@ -62,7 +62,7 @@ public sealed class WorkflowSamplesValidation(ITestOutputHelper outputHelper) :
         return default;
     }
 
-    [Fact]
+    [Fact(Skip = "Azure Functions Core Tools v4 cannot auto-detect worker runtime in CI. See https://github.com/microsoft/agent-framework/issues/6402")]
     public async Task SequentialWorkflowSampleValidationAsync()
     {
         string samplePath = Path.Combine(s_samplesPath, "01_SequentialWorkflow");
@@ -168,7 +168,7 @@ public sealed class WorkflowSamplesValidation(ITestOutputHelper outputHelper) :
         });
     }
 
-    [Fact]
+    [Fact(Skip = "Azure Functions Core Tools v4 cannot auto-detect worker runtime in CI. See https://github.com/microsoft/agent-framework/issues/6402")]
     public async Task HITLWorkflowSampleValidationAsync()
     {
         string samplePath = Path.Combine(s_samplesPath, "03_WorkflowHITL");
@@ -277,7 +277,7 @@ public sealed class WorkflowSamplesValidation(ITestOutputHelper outputHelper) :
         });
     }
 
-    [Fact]
+    [Fact(Skip = "Azure Functions Core Tools v4 cannot auto-detect worker runtime in CI. See https://github.com/microsoft/agent-framework/issues/6402")]
     public async Task WorkflowMcpToolSampleValidationAsync()
     {
         string samplePath = Path.Combine(s_samplesPath, "04_WorkflowMcpTool");
@@ -333,7 +333,7 @@ public sealed class WorkflowSamplesValidation(ITestOutputHelper outputHelper) :
         });
     }
 
-    [Fact]
+    [Fact(Skip = "Azure Functions Core Tools v4 cannot auto-detect worker runtime in CI. See https://github.com/microsoft/agent-framework/issues/6402")]
     public async Task WorkflowAndAgentsSampleValidationAsync()
     {
         string samplePath = Path.Combine(s_samplesPath, "05_WorkflowAndAgents");
@@ -385,7 +385,7 @@ public sealed class WorkflowSamplesValidation(ITestOutputHelper outputHelper) :
         });
     }
 
-    [Fact]
+    [Fact(Skip = "Azure Functions Core Tools v4 cannot auto-detect worker runtime in CI. See https://github.com/microsoft/agent-framework/issues/6402")]
     public async Task ConcurrentWorkflowSampleValidationAsync()
     {
         string samplePath = Path.Combine(s_samplesPath, "02_ConcurrentWorkflow");

dotnet/tests/Microsoft.Agents.AI.Hosting.UnitTests/ClaimsIdentitySessionIsolationKeyProviderTests.cs

@@ -16,6 +16,7 @@ public class ClaimsIdentitySessionIsolationKeyProviderTests
     private const string TestUserId = "test-user-id";
     private const string CustomClaimType = "custom-claim-type";
     private const string CustomClaimValue = "custom-claim-value";
+    private const string TestAuthenticationType = "TestAuth";
 
     private readonly Mock<IHttpContextAccessor> _httpContextAccessorMock;
 
@@ -101,7 +102,7 @@ public class ClaimsIdentitySessionIsolationKeyProviderTests
     public async Task GetSessionIsolationKeyAsyncExtractsDefaultClaimTypeAsync()
     {
         // Arrange
-        this.SetupHttpContextWithClaim(ClaimsIdentity.DefaultNameClaimType, TestUserId);
+        this.SetupHttpContextWithClaim(ClaimTypes.NameIdentifier, TestUserId);
         var provider = new ClaimsIdentitySessionIsolationKeyProvider(this._httpContextAccessorMock.Object);
 
         // Act
@@ -111,6 +112,25 @@ public class ClaimsIdentitySessionIsolationKeyProviderTests
         Assert.Equal(TestUserId, result);
     }
 
+    /// <summary>
+    /// Verify that the default claim type is the stable, unique NameIdentifier claim rather than the
+    /// non-unique display name claim. This guards against the session-isolation collision described in
+    /// the security report where two principals sharing the same name claim received the same key.
+    /// </summary>
+    [Fact]
+    public async Task GetSessionIsolationKeyAsyncIgnoresNameClaimByDefaultAsync()
+    {
+        // Arrange - only a display-name claim is present; the default provider must not use it.
+        this.SetupHttpContextWithClaim(ClaimsIdentity.DefaultNameClaimType, TestUserId);
+        var provider = new ClaimsIdentitySessionIsolationKeyProvider(this._httpContextAccessorMock.Object);
+
+        // Act
+        string? result = await provider.GetSessionIsolationKeyAsync();
+
+        // Assert
+        Assert.Null(result);
+    }
+
     /// <summary>
     /// Verify that GetSessionIsolationKeyAsync uses custom claim type when specified.
     /// </summary>
@@ -191,10 +211,10 @@ public class ClaimsIdentitySessionIsolationKeyProviderTests
         const string SecondValue = "second-value";
         var claims = new[]
         {
-            new Claim(ClaimsIdentity.DefaultNameClaimType, FirstValue),
-            new Claim(ClaimsIdentity.DefaultNameClaimType, SecondValue),
+            new Claim(ClaimTypes.NameIdentifier, FirstValue),
+            new Claim(ClaimTypes.NameIdentifier, SecondValue),
         };
-        var identity = new ClaimsIdentity(claims);
+        var identity = new ClaimsIdentity(claims, TestAuthenticationType);
         var principal = new ClaimsPrincipal(identity);
 
         var httpContext = new DefaultHttpContext
@@ -219,7 +239,7 @@ public class ClaimsIdentitySessionIsolationKeyProviderTests
     public async Task GetSessionIsolationKeyAsyncHandlesEmptyClaimValueAsync()
     {
         // Arrange
-        this.SetupHttpContextWithClaim(ClaimsIdentity.DefaultNameClaimType, string.Empty);
+        this.SetupHttpContextWithClaim(ClaimTypes.NameIdentifier, string.Empty);
         var provider = new ClaimsIdentitySessionIsolationKeyProvider(this._httpContextAccessorMock.Object);
 
         // Act
@@ -229,6 +249,66 @@ public class ClaimsIdentitySessionIsolationKeyProviderTests
         Assert.Equal(string.Empty, result);
     }
 
+    /// <summary>
+    /// Regression test for the session-isolation collision security report: two distinct authenticated
+    /// principals that share the same display-name claim but have different stable identifiers and tenants
+    /// must produce distinct isolation keys under the default options.
+    /// </summary>
+    [Fact]
+    public async Task GetSessionIsolationKeyAsyncDistinctForPrincipalsSharingNameClaimAsync()
+    {
+        // Arrange - both principals share the same name claim but differ by NameIdentifier and tenant.
+        const string CommonName = "John Doe";
+
+        var principalA = CreatePrincipal(
+            new Claim(ClaimsIdentity.DefaultNameClaimType, CommonName),
+            new Claim(ClaimTypes.NameIdentifier, "oid-user-a"),
+            new Claim("http://schemas.microsoft.com/identity/claims/tenantid", "tenant-a"));
+
+        var principalB = CreatePrincipal(
+            new Claim(ClaimsIdentity.DefaultNameClaimType, CommonName),
+            new Claim(ClaimTypes.NameIdentifier, "oid-user-b"),
+            new Claim("http://schemas.microsoft.com/identity/claims/tenantid", "tenant-b"));
+
+        var provider = new ClaimsIdentitySessionIsolationKeyProvider(this._httpContextAccessorMock.Object);
+
+        // Act
+        this._httpContextAccessorMock.Setup(x => x.HttpContext).Returns(new DefaultHttpContext { User = principalA });
+        string? principalAKey = await provider.GetSessionIsolationKeyAsync();
+
+        this._httpContextAccessorMock.Setup(x => x.HttpContext).Returns(new DefaultHttpContext { User = principalB });
+        string? principalBKey = await provider.GetSessionIsolationKeyAsync();
+
+        // Assert
+        Assert.Equal("oid-user-a", principalAKey);
+        Assert.Equal("oid-user-b", principalBKey);
+        Assert.NotEqual(principalAKey, principalBKey);
+    }
+
+    /// <summary>
+    /// Verify that GetSessionIsolationKeyAsync returns null when the request's user is not authenticated,
+    /// even if a claim of the configured type is present. The provider must not derive an isolation key
+    /// from claims on an unauthenticated identity.
+    /// </summary>
+    [Fact]
+    public async Task GetSessionIsolationKeyAsyncReturnsNullWhenUserNotAuthenticatedAsync()
+    {
+        // Arrange - identity has the claim but no authentication type, so IsAuthenticated is false.
+        var claims = new[] { new Claim(ClaimTypes.NameIdentifier, TestUserId) };
+        var unauthenticatedIdentity = new ClaimsIdentity(claims);
+        var principal = new ClaimsPrincipal(unauthenticatedIdentity);
+        var httpContext = new DefaultHttpContext { User = principal };
+        this._httpContextAccessorMock.Setup(x => x.HttpContext).Returns(httpContext);
+        var provider = new ClaimsIdentitySessionIsolationKeyProvider(this._httpContextAccessorMock.Object);
+
+        // Act
+        string? result = await provider.GetSessionIsolationKeyAsync();
+
+        // Assert
+        Assert.False(unauthenticatedIdentity.IsAuthenticated);
+        Assert.Null(result);
+    }
+
     #endregion
 
     #region Helper Methods
@@ -236,7 +316,7 @@ public class ClaimsIdentitySessionIsolationKeyProviderTests
     private void SetupHttpContextWithClaim(string claimType, string claimValue)
     {
         var claims = new[] { new Claim(claimType, claimValue) };
-        var identity = new ClaimsIdentity(claims);
+        var identity = new ClaimsIdentity(claims, TestAuthenticationType);
         var principal = new ClaimsPrincipal(identity);
 
         var httpContext = new DefaultHttpContext
@@ -247,5 +327,8 @@ public class ClaimsIdentitySessionIsolationKeyProviderTests
         this._httpContextAccessorMock.Setup(x => x.HttpContext).Returns(httpContext);
     }
 
+    private static ClaimsPrincipal CreatePrincipal(params Claim[] claims)
+        => new(new ClaimsIdentity(claims, TestAuthenticationType));
+
     #endregion
 }

dotnet/tests/Microsoft.Agents.AI.UnitTests/ChatClient/ChatClientAgent_ChatOptionsMergingTests.cs

@@ -347,6 +347,115 @@ public class ChatClientAgent_ChatOptionsMergingTests
         Assert.Equal(expectedSetting, capturedChatOptions.RawRepresentationFactory(null!));
     }
 
+    /// <summary>
+    /// Verify that <see cref="ChatOptions.Reasoning"/> from the request takes priority over the agent's.
+    /// </summary>
+    [Fact]
+    public async Task ChatOptionsMergingUsesRequestReasoningOverAgentReasoningAsync()
+    {
+        // Arrange
+        var agentReasoning = new ReasoningOptions { Effort = ReasoningEffort.Low, Output = ReasoningOutput.Full };
+        var requestReasoning = new ReasoningOptions { Effort = ReasoningEffort.High, Output = ReasoningOutput.Full };
+
+        Mock<IChatClient> mockService = new();
+        ChatOptions? capturedChatOptions = null;
+        mockService.Setup(
+            s => s.GetResponseAsync(
+                It.IsAny<IEnumerable<ChatMessage>>(),
+                It.IsAny<ChatOptions>(),
+                It.IsAny<CancellationToken>()))
+            .Callback<IEnumerable<ChatMessage>, ChatOptions, CancellationToken>((msgs, opts, ct) =>
+                capturedChatOptions = opts)
+            .ReturnsAsync(new ChatResponse([new(ChatRole.Assistant, "response")]));
+
+        ChatClientAgent agent = new(mockService.Object, options: new()
+        {
+            ChatOptions = new ChatOptions { Reasoning = agentReasoning }
+        });
+        var messages = new List<ChatMessage> { new(ChatRole.User, "test") };
+
+        // Act
+        await agent.RunAsync(messages, options: new ChatClientAgentRunOptions(new ChatOptions { Reasoning = requestReasoning }));
+
+        // Assert
+        Assert.NotNull(capturedChatOptions);
+        Assert.NotNull(capturedChatOptions.Reasoning);
+        Assert.Equal(requestReasoning.Effort, capturedChatOptions.Reasoning.Effort);
+        Assert.Equal(requestReasoning.Output, capturedChatOptions.Reasoning.Output);
+    }
+
+    /// <summary>
+    /// Verify that <see cref="ChatOptions.Reasoning"/> falls back to the agent's when the request has none.
+    /// </summary>
+    [Fact]
+    public async Task ChatOptionsMergingFallsBackToAgentReasoningWhenRequestHasNoneAsync()
+    {
+        // Arrange
+        var agentReasoning = new ReasoningOptions { Effort = ReasoningEffort.Low, Output = ReasoningOutput.Full };
+
+        Mock<IChatClient> mockService = new();
+        ChatOptions? capturedChatOptions = null;
+        mockService.Setup(
+            s => s.GetResponseAsync(
+                It.IsAny<IEnumerable<ChatMessage>>(),
+                It.IsAny<ChatOptions>(),
+                It.IsAny<CancellationToken>()))
+            .Callback<IEnumerable<ChatMessage>, ChatOptions, CancellationToken>((msgs, opts, ct) =>
+                capturedChatOptions = opts)
+            .ReturnsAsync(new ChatResponse([new(ChatRole.Assistant, "response")]));
+
+        ChatClientAgent agent = new(mockService.Object, options: new()
+        {
+            ChatOptions = new ChatOptions { Reasoning = agentReasoning }
+        });
+        var messages = new List<ChatMessage> { new(ChatRole.User, "test") };
+
+        // Act
+        await agent.RunAsync(messages, options: new ChatClientAgentRunOptions(new ChatOptions()));
+
+        // Assert
+        Assert.NotNull(capturedChatOptions);
+        Assert.NotNull(capturedChatOptions.Reasoning);
+        Assert.Equal(agentReasoning.Effort, capturedChatOptions.Reasoning.Effort);
+        Assert.Equal(agentReasoning.Output, capturedChatOptions.Reasoning.Output);
+    }
+
+    /// <summary>
+    /// Verify that <see cref="ChatOptions.Reasoning"/> from the request is used when the agent has none.
+    /// </summary>
+    [Fact]
+    public async Task ChatOptionsMergingUsesRequestReasoningWhenAgentHasNoneAsync()
+    {
+        // Arrange
+        var requestReasoning = new ReasoningOptions { Effort = ReasoningEffort.High, Output = ReasoningOutput.Full };
+
+        Mock<IChatClient> mockService = new();
+        ChatOptions? capturedChatOptions = null;
+        mockService.Setup(
+            s => s.GetResponseAsync(
+                It.IsAny<IEnumerable<ChatMessage>>(),
+                It.IsAny<ChatOptions>(),
+                It.IsAny<CancellationToken>()))
+            .Callback<IEnumerable<ChatMessage>, ChatOptions, CancellationToken>((msgs, opts, ct) =>
+                capturedChatOptions = opts)
+            .ReturnsAsync(new ChatResponse([new(ChatRole.Assistant, "response")]));
+
+        ChatClientAgent agent = new(mockService.Object, options: new()
+        {
+            ChatOptions = new ChatOptions()
+        });
+        var messages = new List<ChatMessage> { new(ChatRole.User, "test") };
+
+        // Act
+        await agent.RunAsync(messages, options: new ChatClientAgentRunOptions(new ChatOptions { Reasoning = requestReasoning }));
+
+        // Assert
+        Assert.NotNull(capturedChatOptions);
+        Assert.NotNull(capturedChatOptions.Reasoning);
+        Assert.Equal(requestReasoning.Effort, capturedChatOptions.Reasoning.Effort);
+        Assert.Equal(requestReasoning.Output, capturedChatOptions.Reasoning.Output);
+    }
+
     /// <summary>
     /// Verify that ChatOptions merging handles all scalar properties correctly.
     /// </summary>

dotnet/tests/Microsoft.Agents.AI.Workflows.UnitTests/MagenticOrchestrationTests.cs

@@ -419,6 +419,82 @@ public class MagenticOrchestrationTests
             "final-answer synthesis must see what participants actually said");
     }
 
+    [Fact]
+    public async Task Participant_Receives_Prior_Participant_Response_Not_InstructionAsync()
+    {
+        // Regression: each participant must see prior participants' *responses* (the running conversation),
+        // not their *instructions*. Previously the orchestrator broadcast the per-round instruction to every
+        // participant (untargeted fan-out) and never broadcast replies, so a later speaker received the earlier
+        // speaker's instruction and never its answer.
+        const string HealthInstruction = "HEALTH_CHECKER_INSTRUCTION_check_framework";
+        const string DatabaseInstruction = "DATABASE_CHECKER_INSTRUCTION_check_database";
+        const string HealthEchoPrefix = "HC_RESPONSE::";
+        const string DatabaseEchoPrefix = "DB_RESPONSE::";
+
+        List<ChatMessage> facts = CreatePlanResponse("Facts");
+        List<ChatMessage> plan = CreatePlanResponse("Plan");
+        List<ChatMessage> round1Ledger = CreateProgressLedgerResponse(
+            isRequestSatisfied: false,
+            isInLoop: false,
+            isProgressBeingMade: true,
+            nextSpeaker: "HealthChecker",
+            instructionOrQuestion: HealthInstruction);
+        List<ChatMessage> round2Ledger = CreateProgressLedgerResponse(
+            isRequestSatisfied: false,
+            isInLoop: false,
+            isProgressBeingMade: true,
+            nextSpeaker: "DatabaseChecker",
+            instructionOrQuestion: DatabaseInstruction);
+        List<ChatMessage> round3Ledger = CreateProgressLedgerResponse(
+            isRequestSatisfied: true,
+            isInLoop: false,
+            isProgressBeingMade: true,
+            nextSpeaker: "DatabaseChecker",
+            instructionOrQuestion: "Done");
+        List<ChatMessage> finalAnswer = CreateFinalAnswerResponse("All systems checked");
+
+        TestReplayAgent manager = new(
+            [facts, plan, round1Ledger, round2Ledger, round3Ledger, finalAnswer],
+            name: "Manager");
+        RecordingEchoAgent healthChecker = new(name: "HealthChecker", prefix: HealthEchoPrefix);
+        RecordingEchoAgent databaseChecker = new(name: "DatabaseChecker", prefix: DatabaseEchoPrefix);
+
+        Workflow workflow = new MagenticWorkflowBuilder(manager)
+            .AddParticipants(healthChecker, databaseChecker)
+            .RequirePlanSignoff(false)
+            .Build();
+
+        WorkflowRunResult runResult = await RunMagenticWorkflowAsync(
+            workflow,
+            [new ChatMessage(ChatRole.User, "Check system health")]);
+
+        runResult.Result.Should().NotBeNull();
+        runResult.Result![0].Text.Should().Contain("All systems checked");
+
+        // Each participant takes exactly one turn.
+        healthChecker.RecordedInputs.Should().ContainSingle();
+        databaseChecker.RecordedInputs.Should().ContainSingle();
+
+        // The first speaker receives its own instruction.
+        List<ChatMessage> healthInput = healthChecker.RecordedInputs[0];
+        healthInput.Should().Contain(m => m.Text.Contains(HealthInstruction), "the first speaker receives its own instruction");
+
+        // The second speaker must see the first speaker's RESPONSE (authored by HealthChecker, carrying the echo
+        // prefix that only the response — not the raw instruction — has), plus its own instruction.
+        List<ChatMessage> databaseInput = databaseChecker.RecordedInputs[0];
+        databaseInput.Should().Contain(
+            m => m.AuthorName == "HealthChecker" && m.Text.Contains(HealthEchoPrefix),
+            "the next speaker must receive the prior participant's response (the running conversation)");
+        databaseInput.Should().Contain(m => m.Text.Contains(DatabaseInstruction),
+            "the next speaker must receive its own instruction");
+
+        // The leaked-instruction bug: the second speaker must not receive HealthChecker's instruction as a
+        // bare message (it should only appear, if at all, embedded in HealthChecker's prefixed response).
+        databaseInput.Should().NotContain(
+            m => m.AuthorName != "HealthChecker" && m.Text.Trim() == HealthInstruction,
+            "the prior speaker's instruction must not leak into the next speaker's context as a standalone message");
+    }
+
     [Fact]
     public async Task PlanReview_Revised_Triggers_ReplanAsync()
     {

dotnet/tests/Microsoft.Agents.AI.Workflows.UnitTests/RecordingEchoAgent.cs

@@ -0,0 +1,37 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Collections.Generic;
+using System.Linq;
+using System.Runtime.CompilerServices;
+using System.Threading;
+using Microsoft.Extensions.AI;
+
+namespace Microsoft.Agents.AI.Workflows.UnitTests;
+
+/// <summary>
+/// A <see cref="TestEchoAgent"/> that records the input messages it receives on each call.
+/// Used by tests that need to assert what context a participant was actually handed - for example,
+/// that a later speaker sees prior participants' <em>responses</em> (the running conversation) rather
+/// than their <em>instructions</em>.
+/// </summary>
+internal sealed class RecordingEchoAgent(string? id = null, string? name = null, string? prefix = null)
+    : TestEchoAgent(id, name, prefix)
+{
+    public List<List<ChatMessage>> RecordedInputs { get; } = [];
+
+    protected override async IAsyncEnumerable<AgentResponseUpdate> RunCoreStreamingAsync(
+        IEnumerable<ChatMessage> messages,
+        AgentSession? session = null,
+        AgentRunOptions? options = null,
+        [EnumeratorCancellation] CancellationToken cancellationToken = default)
+    {
+        // Materialize once so the deferred input is recorded and replayed identically.
+        List<ChatMessage> recorded = messages.ToList();
+        this.RecordedInputs.Add(recorded);
+
+        await foreach (AgentResponseUpdate update in base.RunCoreStreamingAsync(recorded, session, options, cancellationToken))
+        {
+            yield return update;
+        }
+    }
+}

python/CHANGELOG.md

@@ -7,6 +7,26 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.8.1] - 2026-06-09
+
+### Added
+- **agent-framework-core**: Add MCP client OTel spans per GenAI semantic conventions ([#6349](https://github.com/microsoft/agent-framework/pull/6349))
+- **agent-framework-core**: Add MCP long-running task support ([#6319](https://github.com/microsoft/agent-framework/pull/6319))
+
+### Changed
+- **agent-framework-claude**: Bump `claude-agent-sdk` to 0.2.87 ([#6248](https://github.com/microsoft/agent-framework/pull/6248))
+- **agent-framework-core**: Document checkpoint storage security model and deserialization trust boundaries ([#6295](https://github.com/microsoft/agent-framework/pull/6295))
+- **agent-framework-azurefunctions**: Document checkpoint storage security model and deserialization trust boundaries ([#6295](https://github.com/microsoft/agent-framework/pull/6295))
+
+### Fixed
+- **agent-framework-core**: Filter MCP tool kwargs to declared params via allowlist ([#6399](https://github.com/microsoft/agent-framework/pull/6399))
+- **agent-framework-core**: Fix per-service-call history persistence with server-storing clients ([#6310](https://github.com/microsoft/agent-framework/pull/6310))
+- **agent-framework-openai**: Use `getattr` for non-OpenAI provider response compatibility ([#6270](https://github.com/microsoft/agent-framework/pull/6270))
+- **agent-framework-foundry-hosting**: Refactor workflow-as-agent pending request handling ([#6259](https://github.com/microsoft/agent-framework/pull/6259))
+- **agent-framework-gemini**: Make Gemini honor declarative `outputSchema`, not just JSON mode ([#5893](https://github.com/microsoft/agent-framework/pull/5893))
+- **agent-framework-mem0**: Isolate entity retrieval and correct `app_id` payload ([#6242](https://github.com/microsoft/agent-framework/pull/6242))
+- **agent-framework-ag-ui**: Match AG-UI approval responses to requested arguments ([#6376](https://github.com/microsoft/agent-framework/pull/6376))
+
 ## [1.8.0] - 2026-06-04
 
 ### Added
@@ -1169,7 +1189,8 @@ Release candidate for **agent-framework-core** and **agent-framework-azure-ai**
 
 For more information, see the [announcement blog post](https://devblogs.microsoft.com/foundry/introducing-microsoft-agent-framework-the-open-source-engine-for-agentic-ai-apps/).
 
-[Unreleased]: https://github.com/microsoft/agent-framework/compare/python-1.8.0...HEAD
+[Unreleased]: https://github.com/microsoft/agent-framework/compare/python-1.8.1...HEAD
+[1.8.1]: https://github.com/microsoft/agent-framework/compare/python-1.8.0...python-1.8.1
 [1.8.0]: https://github.com/microsoft/agent-framework/compare/python-1.7.0...python-1.8.0
 [1.7.0]: https://github.com/microsoft/agent-framework/compare/python-1.6.0...python-1.7.0
 [1.6.0]: https://github.com/microsoft/agent-framework/compare/python-1.5.0...python-1.6.0

python/packages/ag-ui/agent_framework_ag_ui/_agent.py

@@ -9,7 +9,7 @@ from typing import Any, cast
 from ag_ui.core import BaseEvent
 from agent_framework import SupportsAgentRun
 
-from ._agent_run import run_agent_stream
+from ._agent_run import PendingApprovalEntry, run_agent_stream
 
 
 class AgentConfig:
@@ -107,7 +107,7 @@ class AgentFrameworkAgent:
         # Populated when approval requests are emitted; consumed when responses arrive.
         # Prevents bypass, function name spoofing, and replay attacks.
         # Bounded to prevent unbounded growth from abandoned approval requests.
-        self._pending_approvals: OrderedDict[str, str] = OrderedDict()
+        self._pending_approvals: OrderedDict[str, PendingApprovalEntry] = OrderedDict()
         self._pending_approvals_max_size: int = 10_000
 
     async def run(

python/packages/ag-ui/agent_framework_ag_ui/_agent_run.py

@@ -8,7 +8,7 @@ import json
 import logging
 import uuid
 from collections.abc import AsyncIterable, Awaitable
-from typing import TYPE_CHECKING, Any, cast
+from typing import TYPE_CHECKING, Any, TypedDict, cast
 
 from ag_ui.core import (
     BaseEvent,
@@ -56,6 +56,7 @@ from ._run_common import (
     _stringify_tool_result,  # type: ignore
 )
 from ._utils import (
+    canonical_function_arguments,
     convert_agui_tools_to_agent_framework,
     generate_event_id,
     get_conversation_id_from_update,
@@ -407,7 +408,33 @@ def _make_approval_tool_result_events(resolved_approval_results: list[Content])
     return events
 
 
-def _evict_oldest_approvals(registry: dict[str, str], max_size: int = 10_000) -> None:
+class _PendingApproval(TypedDict):
+    """Pending approval details for a requested function call."""
+
+    name: str
+    arguments: str | None
+
+
+PendingApprovalEntry = _PendingApproval | str
+
+
+def _make_pending_approval_entry(name: str, arguments: str | None) -> _PendingApproval:
+    return {"name": name, "arguments": arguments}
+
+
+def _pending_approval_name(entry: PendingApprovalEntry) -> str | None:
+    if isinstance(entry, str):
+        return entry
+    return entry["name"]
+
+
+def _pending_approval_arguments(entry: PendingApprovalEntry) -> str | None:
+    if isinstance(entry, str):
+        return None
+    return entry["arguments"]
+
+
+def _evict_oldest_approvals(registry: dict[str, PendingApprovalEntry], max_size: int = 10_000) -> None:
     """Evict the oldest entries from the pending-approvals registry (LRU).
 
     Only effective when *registry* is an ``OrderedDict``;  plain dicts are
@@ -427,7 +454,7 @@ async def _resolve_approval_responses(
     tools: list[Any],
     agent: SupportsAgentRun,
     run_kwargs: dict[str, Any],
-    pending_approvals: dict[str, str] | None = None,
+    pending_approvals: dict[str, PendingApprovalEntry] | None = None,
     thread_id: str = "",
 ) -> list[Content]:
     """Execute approved function calls and replace approval content with results.
@@ -480,7 +507,8 @@ async def _resolve_approval_responses(
                 invalid_ids.add(resp_id)
                 continue
 
-            pending_name = pending_approvals[registry_key]
+            pending_entry = pending_approvals[registry_key]
+            pending_name = _pending_approval_name(pending_entry)
             if resp_name != pending_name:
                 logger.warning(
                     "Rejected approval response id=%s: function name mismatch (response=%s, pending=%s)",
@@ -491,6 +519,16 @@ async def _resolve_approval_responses(
                 invalid_ids.add(resp_id)
                 continue
 
+            pending_arguments = _pending_approval_arguments(pending_entry)
+            response_arguments = canonical_function_arguments(resp.function_call)
+            if pending_arguments is not None and response_arguments != pending_arguments:
+                logger.warning(
+                    "Rejected approval response id=%s: function arguments mismatch",
+                    resp_id,
+                )
+                invalid_ids.add(resp_id)
+                continue
+
             # Valid — consume entry to prevent replay
             del pending_approvals[registry_key]
             if resp.approved:
@@ -714,7 +752,7 @@ async def run_agent_stream(
     input_data: dict[str, Any],
     agent: SupportsAgentRun,
     config: AgentConfig,
-    pending_approvals: dict[str, str] | None = None,
+    pending_approvals: dict[str, PendingApprovalEntry] | None = None,
 ) -> AsyncGenerator[BaseEvent]:
     """Run agent and yield AG-UI events.
 
@@ -917,7 +955,10 @@ async def run_agent_stream(
             # Register pending approval requests so we can validate responses later
             if content_type == "function_approval_request" and pending_approvals is not None:
                 if content.id and content.function_call and content.function_call.name:
-                    pending_approvals[f"{thread_id}:{content.id}"] = content.function_call.name
+                    pending_approvals[f"{thread_id}:{content.id}"] = _make_pending_approval_entry(
+                        content.function_call.name,
+                        canonical_function_arguments(content.function_call),
+                    )
                     # Evict oldest entries if the registry exceeds a safe bound (LRU)
                     _evict_oldest_approvals(pending_approvals, max_size=10_000)
                 else:

python/packages/ag-ui/agent_framework_ag_ui/_utils.py

@@ -56,6 +56,22 @@ def safe_json_parse(value: Any) -> dict[str, Any] | None:
     return None
 
 
+def canonical_function_arguments(function_call: Any) -> str | None:
+    """Return a stable representation of function-call arguments."""
+    if function_call is None:
+        return None
+
+    try:
+        parsed_arguments = function_call.parse_arguments()
+    except Exception:
+        parsed_arguments = getattr(function_call, "arguments", None)
+
+    if parsed_arguments is None:
+        parsed_arguments = {}
+
+    return json.dumps(make_json_safe(parsed_arguments), sort_keys=True, separators=(",", ":"))
+
+
 def get_role_value(message: Any) -> str:
     """Extract role string from a message object.
 

python/packages/ag-ui/agent_framework_ag_ui/_workflow_run.py

@@ -35,7 +35,7 @@ from ._run_common import (
     _extract_resume_payload,
     _normalize_resume_interrupts,
 )
-from ._utils import generate_event_id, make_json_safe
+from ._utils import canonical_function_arguments, generate_event_id, make_json_safe
 
 logger = logging.getLogger(__name__)
 
@@ -324,6 +324,29 @@ def _coerce_response_for_request(request_event: Any, value: Any) -> Any | None:
     return candidate
 
 
+def _approval_response_matches_request(request_id: str, request_event: Any, response: Any) -> bool:
+    """Check whether an approval response matches the pending approval request."""
+    request_data = getattr(request_event, "data", None)
+    if not isinstance(request_data, Content) or request_data.type != "function_approval_request":
+        return True
+
+    if not isinstance(response, Content) or response.type != "function_approval_response":
+        return False
+
+    if str(getattr(response, "id", "")) != request_id:
+        return False
+
+    request_call = getattr(request_data, "function_call", None)
+    response_call = getattr(response, "function_call", None)
+    if request_call is None or response_call is None:
+        return False
+
+    if getattr(response_call, "name", None) != getattr(request_call, "name", None):
+        return False
+
+    return canonical_function_arguments(response_call) == canonical_function_arguments(request_call)
+
+
 def _single_pending_response_from_value(pending_events: dict[str, Any], value: Any) -> dict[str, Any]:
     """Map a scalar resume payload to the single pending request (if unambiguous)."""
     if value is None or len(pending_events) != 1:
@@ -343,6 +366,13 @@ def _single_pending_response_from_value(pending_events: dict[str, Any], value: A
         )
         return {}
 
+    if not _approval_response_matches_request(str(request_id), request_event, coerced_value):
+        logger.info(
+            "Ignoring pending request response for request_id=%s: approval response does not match pending request",
+            request_id,
+        )
+        return {}
+
     return {str(request_id): coerced_value}
 
 
@@ -372,6 +402,12 @@ def _coerce_responses_for_pending_requests(
                 _response_type_name(request_event),
             )
             continue
+        if not _approval_response_matches_request(request_key, request_event, coerced_value):
+            logger.info(
+                "Ignoring resume response for request_id=%s: approval response does not match pending request",
+                request_key,
+            )
+            continue
         normalized[request_key] = coerced_value
     return normalized
 

python/packages/ag-ui/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "agent-framework-ag-ui"
-version = "1.0.0rc3"
+version = "1.0.0rc4"
 description = "AG-UI protocol integration for Agent Framework"
 readme = "README.md"
 license-files = ["LICENSE"]
@@ -22,7 +22,7 @@ classifiers = [
   "Typing :: Typed",
 ]
 dependencies = [
-    "agent-framework-core>=1.6.0,<2",
+    "agent-framework-core>=1.8.1,<2",
     "ag-ui-protocol>=0.1.16,<0.2",
     "fastapi>=0.115.0,<0.133.1",
     "uvicorn[standard]>=0.30.0,<1"

python/packages/ag-ui/tests/ag_ui/test_agent_wrapper_comprehensive.py

@@ -1407,6 +1407,92 @@ async def test_fabricated_rejection_without_pending_approval_is_blocked(streamin
                 assert False, "Fabricated rejection response leaked as function_result into LLM messages"
 
 
+async def test_approval_argument_mismatch_is_blocked(streaming_chat_client_stub):
+    """An approval response must not execute changed arguments for the pending call."""
+    from agent_framework import tool
+    from agent_framework.ag_ui import AgentFrameworkAgent
+
+    executed_args: list[dict[str, Any]] = []
+
+    @tool(
+        name="update_record",
+        description="Update a record",
+        approval_mode="always_require",
+    )
+    def update_record(record_id: str, value: str) -> str:
+        executed_args.append({"record_id": record_id, "value": value})
+        return f"updated {record_id} to {value}"
+
+    async def stream_fn_approval(
+        messages: MutableSequence[Message], options: ChatOptions, **kwargs: Any
+    ) -> AsyncIterator[ChatResponseUpdate]:
+        yield ChatResponseUpdate(
+            contents=[
+                Content.from_function_call(
+                    name="update_record",
+                    call_id="call_update_001",
+                    arguments={"record_id": "alpha", "value": "approved"},
+                )
+            ]
+        )
+
+    wrapper = AgentFrameworkAgent(
+        agent=Agent(
+            client=streaming_chat_client_stub(stream_fn_approval),
+            name="test_agent",
+            instructions="Test",
+            tools=[update_record],
+        )
+    )
+    thread_id = "thread-argument-mismatch-test"
+
+    events1: list[Any] = []
+    async for event in wrapper.run({"thread_id": thread_id, "messages": [{"role": "user", "content": "update"}]}):
+        events1.append(event)
+
+    assert any("call_update_001" in k for k in wrapper._pending_approvals)
+
+    async def stream_fn_post(
+        messages: MutableSequence[Message], options: ChatOptions, **kwargs: Any
+    ) -> AsyncIterator[ChatResponseUpdate]:
+        yield ChatResponseUpdate(contents=[Content.from_text(text="Done")])
+
+    wrapper.agent = Agent(
+        client=streaming_chat_client_stub(stream_fn_post),
+        name="test_agent",
+        instructions="Test",
+        tools=[update_record],
+    )
+
+    turn2_input: dict[str, Any] = {
+        "thread_id": thread_id,
+        "messages": [
+            {
+                "role": "user",
+                "content": "approve",
+                "function_approvals": [
+                    {
+                        "id": "call_update_001",
+                        "call_id": "call_update_001",
+                        "name": "update_record",
+                        "approved": True,
+                        "arguments": {"record_id": "beta", "value": "changed"},
+                    }
+                ],
+            },
+        ],
+    }
+
+    events2: list[Any] = []
+    async for event in wrapper.run(turn2_input):
+        events2.append(event)
+
+    assert executed_args == []
+    assert any("call_update_001" in k for k in wrapper._pending_approvals), (
+        "Pending approval should be preserved after argument mismatch for legitimate retry"
+    )
+
+
 async def test_state_update_end_to_end_via_real_tool_invocation(streaming_chat_client_stub):
     """End-to-end coverage for issue #3167: a real ``@tool`` returning ``state_update`` must
     emit a deterministic STATE_SNAPSHOT through the full pipeline.

python/packages/ag-ui/tests/ag_ui/test_workflow_run.py

@@ -1352,6 +1352,70 @@ async def test_workflow_run_approval_via_messages_approved() -> None:
     assert not resumed_finished.get("interrupt")
 
 
+async def test_workflow_run_approval_argument_mismatch_keeps_interrupt_pending() -> None:
+    """Workflow approval responses must not resume with changed function arguments."""
+
+    handled_responses: list[dict[str, Any]] = []
+
+    class ApprovalExecutor(Executor):
+        def __init__(self) -> None:
+            super().__init__(id="approval_executor")
+
+        @handler
+        async def start(self, message: Any, ctx: WorkflowContext) -> None:
+            del message
+            function_call = Content.from_function_call(
+                call_id="refund-call",
+                name="submit_refund",
+                arguments={"order_id": "12345", "amount": "$89.99"},
+            )
+            approval_request = Content.from_function_approval_request(id="approval-1", function_call=function_call)
+            await ctx.request_info(approval_request, Content, request_id="approval-1")
+
+        @response_handler
+        async def handle_approval(self, original_request: Content, response: Content, ctx: WorkflowContext) -> None:
+            del original_request
+            if response.function_call is not None:
+                handled_responses.append(response.function_call.parse_arguments() or {})
+            await ctx.yield_output("handled")
+
+    workflow = WorkflowBuilder(start_executor=ApprovalExecutor()).build()
+    first_events = [
+        event async for event in run_workflow_stream({"messages": [{"role": "user", "content": "go"}]}, workflow)
+    ]
+    first_finished = [event for event in first_events if event.type == "RUN_FINISHED"][0].model_dump()
+    interrupt_payload = cast(list[dict[str, Any]], first_finished.get("interrupt"))
+    assert isinstance(interrupt_payload, list) and len(interrupt_payload) == 1
+
+    resumed_events = [
+        event
+        async for event in run_workflow_stream(
+            {
+                "messages": [
+                    {
+                        "role": "user",
+                        "content": "",
+                        "function_approvals": [
+                            {
+                                "approved": True,
+                                "id": "approval-1",
+                                "call_id": "refund-call",
+                                "name": "submit_refund",
+                                "arguments": {"order_id": "99999", "amount": "$1000.00"},
+                            }
+                        ],
+                    }
+                ],
+            },
+            workflow,
+        )
+    ]
+
+    assert handled_responses == []
+    resumed_finished = [event for event in resumed_events if event.type == "RUN_FINISHED"][0].model_dump()
+    assert resumed_finished.get("interrupt")
+
+
 async def test_workflow_run_approval_via_messages_denied() -> None:
     """Denied approval response sent via messages (function_approvals) should satisfy the pending request."""
 

python/packages/azurefunctions/agent_framework_azurefunctions/_serialization.py

@@ -14,6 +14,24 @@ This module adds:
 - reconstruct_to_type: for HITL responses where external data (without type markers)
   needs to be reconstructed to a known type
 - resolve_type: resolves 'module:class' type keys to Python types
+
+Security Model
+--------------
+The underlying Azure Durable Functions storage (Azure Storage account) is the
+trusted persistence layer for serialized checkpoint data.  The
+``RestrictedUnpickler`` in the core encoding module provides defense-in-depth
+type filtering, but checkpoint storage itself must be properly access-controlled:
+
+- Ensure the Azure Storage account used by Durable Functions is not publicly
+  writable and uses appropriate RBAC / shared-access policies.
+- Never route untrusted user input directly into ``deserialize_value`` without
+  first calling :func:`strip_pickle_markers` to neutralize injection of
+  pickle markers into the data path.
+- Configure your checkpoint storage with ``allowed_checkpoint_types`` (or call
+  ``decode_checkpoint_value(..., allowed_types=...)`` directly) to restrict the set of types that can be deserialized.
+
+See :mod:`agent_framework._workflows._checkpoint_encoding` for the full
+security model documentation.
 """
 
 from __future__ import annotations

python/packages/azurefunctions/pyproject.toml

@@ -4,7 +4,7 @@ description = "Azure Functions integration for Microsoft Agent Framework."
 authors = [{ name = "Microsoft", email = "af-support@microsoft.com"}]
 readme = "README.md"
 requires-python = ">=3.10"
-version = "1.0.0b260604"
+version = "1.0.0b260609"
 license-files = ["LICENSE"]
 urls.homepage = "https://aka.ms/agent-framework"
 urls.source = "https://github.com/microsoft/agent-framework/tree/main/python"
@@ -22,7 +22,7 @@ classifiers = [
   "Typing :: Typed",
 ]
 dependencies = [
-    "agent-framework-core>=1.8.0,<2",
+    "agent-framework-core>=1.8.1,<2",
     "agent-framework-durabletask>=1.0.0b260604,<2",
     "azure-functions>=1.24.0,<2",
     "azure-functions-durable>=1.3.1,<2",

python/packages/claude/agent_framework_claude/_agent.py

@@ -221,9 +221,31 @@ class ClaudeAgentOptions(TypedDict, total=False):
     thinking: ThinkingConfig
     """Extended thinking configuration (adaptive, enabled, or disabled)."""
 
-    effort: Literal["low", "medium", "high", "max"]
+    effort: Literal["low", "medium", "high", "xhigh", "max"]
     """Effort level for thinking depth."""
 
+    skills: list[str] | Literal["all"]
+    """Skills to enable for the main session. Use ``"all"`` for every discovered skill,
+    a list of named skills, or ``[]`` to suppress all skills."""
+
+    session_id: str
+    """Use a specific session ID (must be a valid UUID) instead of auto-generated."""
+
+    task_budget: dict[str, int]
+    """API-side task budget in tokens for pacing tool use."""
+
+    include_hook_events: bool
+    """When True, hook lifecycle events are emitted in the message stream."""
+
+    strict_mcp_config: bool
+    """When True, only use MCP servers passed via ``mcp_servers``, ignoring all others."""
+
+    continue_conversation: bool
+    """Continue the most recent conversation instead of starting a new one."""
+
+    fork_session: bool
+    """When True, resumed sessions fork to a new session ID."""
+
     on_function_approval: FunctionApprovalCallback
     """Approval callback for ``FunctionTool`` instances declared with
     ``approval_mode="always_require"``. The callback is awaited (sync or async)

python/packages/claude/pyproject.toml

@@ -4,7 +4,7 @@ description = "Claude Agent SDK integration for Microsoft Agent Framework."
 authors = [{ name = "Microsoft", email = "af-support@microsoft.com"}]
 readme = "README.md"
 requires-python = ">=3.10"
-version = "1.0.0b260521"
+version = "1.0.0b260609"
 license-files = ["LICENSE"]
 urls.homepage = "https://aka.ms/agent-framework"
 urls.source = "https://github.com/microsoft/agent-framework/tree/main/python"
@@ -23,8 +23,8 @@ classifiers = [
   "Typing :: Typed",
 ]
 dependencies = [
-    "agent-framework-core>=1.6.0,<2",
-    "claude-agent-sdk>=0.1.36,<0.1.49",
+    "agent-framework-core>=1.8.1,<2",
+    "claude-agent-sdk>=0.1.36,<0.3",
 ]
 
 [tool.uv]

python/packages/core/AGENTS.md

@@ -80,6 +80,8 @@ agent_framework/
 
 - **`MCPTool`** - Base wrapper that owns the MCP `ClientSession` and exposes the remote server's tools as `FunctionTool`s.
 - **`MCPStdioTool`** / **`MCPStreamableHTTPTool`** / **`MCPWebsocketTool`** - Transport-specific subclasses.
+- **Argument allowlist (`_prepare_call_kwargs`)** - Before each `tools/call`, kwargs are filtered to an **allowlist** built from the tool's declared parameters (`inputSchema.properties`) plus any user-configured extras. Framework runtime kwargs injected through the function-invocation pipeline (e.g. `thread`, `conversation_id`, `chat_options`, `options`, `response_format`) are stripped by default rather than forwarded. A tool that declares no usable `properties` (including schemas with `additionalProperties: true`) forwards only the configured extras. The `_MCP_FRAMEWORK_DENYLIST` is a safety net for framework-named params a server *declares* in its schema (those are dropped); names explicitly opted in via `additional_tool_argument_names` always win. The reserved `_meta` key is extracted as MCP request metadata, never forwarded as an argument.
+- **`additional_tool_argument_names`** (constructor arg on all `MCPTool` subclasses) - Opt extra argument names back into the allowlist. Accepts a `Sequence[str]` (applied to every tool) or a `Mapping[str, Sequence[str]]` keyed by **remote tool name**, where the reserved key `"*"` denotes global extras. It is configured only in user code at construction; there is **no per-call/runtime override**, so a model-issued tool call cannot change which names pass through. To use a server that accepts `additionalProperties: true`, list the extra names here and then either (1) manually extend that tool's `inputSchema` (via the `.functions` list after connecting) so the model is prompted to supply them, or (2) supply the values yourself via `function_invocation_kwargs`. If a name is supplied by both the model and `function_invocation_kwargs`, the model-supplied value wins.
 - **`MCPTaskOptions`** (experimental, `MCP_LONG_RUNNING_TASKS` feature, **frozen**) - Per-tool-instance options controlling the SEP-2663 long-running task lifecycle. When the server advertises a tool with `execution.taskSupport == "required"`, `MCPTool.call_tool` transparently routes through `call_tool_as_task`, which sends an augmented `tools/call`, polls `tasks/get` until terminal, and reinterprets `tasks/result` as a normal `CallToolResult`. Instances are immutable; replace via `MCPTool.task_options = MCPTaskOptions(...)`. Fields:
   - `default_ttl: timedelta | None` — forwarded to the server as `params.task.ttl` (milliseconds). When `None`, the server's default applies.
   - `cancel_remote_task_on_local_cancellation: bool = True` — only gates the `CancelledError` path. Abandonment paths (see below) always cancel.

python/packages/core/agent_framework/_agents.py

@@ -92,12 +92,16 @@ OptionsCoT = TypeVar(
 def _merge_options(base: dict[str, Any], override: dict[str, Any]) -> dict[str, Any]:
     """Merge two options dicts, with override values taking precedence.
 
+    ``None`` is treated as "unset": ``None`` overrides are skipped so they don't clobber a base
+    value, and the merged result is stripped of any remaining ``None`` values in a final pass so
+    unset options are never forwarded (e.g. an unset ``store`` is left for the service to default).
+
     Args:
         base: The base options dict.
         override: The override options dict (values take precedence).
 
     Returns:
-        A new merged options dict.
+        A new merged options dict containing no ``None`` values.
     """
     result = dict(base)
 
@@ -123,7 +127,7 @@ def _merge_options(base: dict[str, Any], override: dict[str, Any]) -> dict[str,
             result["instructions"] = f"{result['instructions']}\n{value}"
         else:
             result[key] = value
-    return result
+    return {key: value for key, value in result.items() if value is not None}
 
 
 def _sanitize_agent_name(agent_name: str | None) -> str | None:
@@ -460,6 +464,9 @@ class BaseAgent(SerializationMixin):
         if provider_session is None and self.context_providers:
             provider_session = AgentSession()
 
+        # When per-service-call persistence is enabled, the per-service-call middleware owns
+        # HistoryProvider persistence (in both the local and service-managed cases), so skip
+        # them on the once-per-run path to avoid double persistence.
         per_service_call_history_required = self.require_per_service_call_history_persistence and any(
             isinstance(provider, HistoryProvider) for provider in self.context_providers
         )
@@ -686,11 +693,16 @@ class RawAgent(BaseAgent, Generic[OptionsCoT]):  # type: ignore[misc]
             description: A brief description of the agent's purpose.
             context_providers: Context providers to include during agent invocation.
             middleware: List of middleware to intercept agent and function invocations.
-            require_per_service_call_history_persistence: When True, history providers are invoked
-                around each model call instead of once per ``run()`` when the service
-                is not already storing history. If service-side storage is active for
-                the run, the agent skips local history providers and relies on the
-                service-managed conversation instead.
+            require_per_service_call_history_persistence: When True (and a HistoryProvider is
+                present), the provider always persists history via per-service-call middleware,
+                regardless of whether the client stores history server-side. If the client does
+                not store history, the middleware also loads providers around each model call and
+                drives the function loop with a local conversation; if it does, loading is skipped
+                (the service-managed conversation is the source of truth) and the middleware only
+                persists. A warning is logged for providers with ``load_messages=True`` when
+                loading is skipped because service-side storage is active. When no HistoryProvider
+                is present, this flag has no effect (no middleware is installed and nothing is
+                persisted).
             default_options: A TypedDict containing chat options. When using a typed agent like
                 ``Agent[OpenAIChatOptions]``, this enables IDE autocomplete for
                 provider-specific options including temperature, max_tokens, model,
@@ -791,22 +803,20 @@ class RawAgent(BaseAgent, Generic[OptionsCoT]):  # type: ignore[misc]
         self,
         *,
         session: AgentSession | None,
-        options: Mapping[str, Any] | None,
+        conversation_id: str | None,
         service_stores_history: bool,
     ) -> list[HistoryProvider]:
         history_providers = self._get_history_providers()
         if not self.require_per_service_call_history_persistence or not history_providers:
             return []
 
-        conversation_id = (
-            session.service_session_id
-            if session and session.service_session_id
-            else cast(str | None, (options or {}).get("conversation_id") or self.default_options.get("conversation_id"))
-        )
-        if service_stores_history:
-            return []
-
-        if conversation_id is not None:
+        # A live service-managed session id takes precedence over the resolved conversation id.
+        if session and session.service_session_id:
+            conversation_id = session.service_session_id
+        # Without service-side storage the middleware persists locally and drives the function
+        # loop with a local sentinel, which cannot be reconciled with an existing service-managed
+        # conversation. When the service stores history, an existing conversation id is expected.
+        if conversation_id is not None and not service_stores_history:
             raise AgentInvalidRequestException(
                 "require_per_service_call_history_persistence cannot be used "
                 "with an existing service-managed conversation."
@@ -1167,18 +1177,34 @@ class RawAgent(BaseAgent, Generic[OptionsCoT]):  # type: ignore[misc]
 
         input_messages = normalize_messages(messages)
 
-        # `store` in runtime or agent options takes precedence over client-level storage
-        # indicators. An explicit `store=False` forces local (in-memory) history injection,
-        # even if the client is configured to use service-side storage by default.
-        store_ = opts.get("store", self.default_options.get("store", getattr(self.client, "STORES_BY_DEFAULT", False)))
+        # Combine agent-level defaults with runtime options up front so the decisions below read
+        # `store` from a single place rather than introspecting both dicts. _merge_options applies
+        # the same precedence used for the actual client call (runtime wins; unset/None falls back
+        # to the agent default).
+        effective_options = _merge_options(self.default_options, opts)
+
+        # `store` in runtime or agent options takes precedence over the client's default
+        # storage behavior. An explicit `store=False` forces local (in-memory) history
+        # injection even when the client stores server-side by default; an explicit
+        # `store=True` forces service-side storage. A `store=None`/unset value means the
+        # service falls back to its own default.
+        explicit_store = effective_options.get("store")
+        # Internal behavior hint: will the service own history for this run? Only when the
+        # user left `store` unset do we fall back to the client's STORES_BY_DEFAULT.
+        service_stores_history = (
+            explicit_store if explicit_store is not None else getattr(self.client, "STORES_BY_DEFAULT", False)
+        )
+        # Resolve conversation_id from the same combined view so an agent-level default is honored
+        # when the runtime omits it (a live session id still takes precedence below).
+        effective_conversation_id = effective_options.get("conversation_id")
         # Auto-inject InMemoryHistoryProvider when session is provided, no context providers
         # registered, and no service-side storage indicators
         if (
             session is not None
             and not self.context_providers
             and not session.service_session_id
-            and not opts.get("conversation_id")
-            and not store_
+            and not effective_conversation_id
+            and not service_stores_history
         ):
             self.context_providers.append(InMemoryHistoryProvider())
 
@@ -1188,10 +1214,30 @@ class RawAgent(BaseAgent, Generic[OptionsCoT]):  # type: ignore[misc]
 
         per_service_call_history_providers = self._resolve_per_service_call_history_providers(
             session=active_session,
-            options=opts,
-            service_stores_history=bool(store_),
+            conversation_id=effective_conversation_id,
+            service_stores_history=service_stores_history,
         )
 
+        # When require_per_service_call_history_persistence is set together with a
+        # HistoryProvider, the per-service-call middleware (installed below) always persists
+        # the provider. ``service_stores_history`` only selects how the middleware behaves:
+        # - service does not store: the middleware also loads providers and drives the function
+        #   loop with a local sentinel conversation id, or
+        # - service stores: the middleware skips loading (the service owns history) and simply
+        #   persists each service call while the real conversation id flows through.
+        # In the service-managed case loading is skipped, so warn for providers that expect to load.
+        history_providers = self._get_history_providers()
+        if self.require_per_service_call_history_persistence and history_providers and service_stores_history:
+            for provider in history_providers:
+                if provider.load_messages:
+                    logger.warning(
+                        "HistoryProvider '%s' has load_messages=True but the chat client stores history "
+                        "server-side; skipping local history load and relying on the service-managed "
+                        "conversation. Set store=False to load from the provider, or load_messages=False "
+                        "to silence this warning.",
+                        provider.source_id,
+                    )
+
         session_context, chat_options = await self._prepare_session_and_messages(
             session=active_session,
             input_messages=input_messages,
@@ -1265,8 +1311,8 @@ class RawAgent(BaseAgent, Generic[OptionsCoT]):  # type: ignore[misc]
         }
         if model is not None:
             run_opts["model"] = model
-        # Remove None values and merge with chat_options
-        run_opts = {k: v for k, v in run_opts.items() if v is not None}
+        # _merge_options strips unset (None) options, so e.g. an unset `store` is not forwarded
+        # and the service decides its own default.
         co = _merge_options(chat_options, run_opts)
 
         # Build session_messages from session context: context messages + input messages
@@ -1280,6 +1326,7 @@ class RawAgent(BaseAgent, Generic[OptionsCoT]):  # type: ignore[misc]
                 agent=self,
                 session=active_session,
                 providers=per_service_call_history_providers,
+                service_stores_history=service_stores_history,
             )
             existing_middleware = effective_client_kwargs.get("middleware")
             if isinstance(existing_middleware, Sequence) and not isinstance(existing_middleware, (str, bytes)):
@@ -1319,7 +1366,7 @@ class RawAgent(BaseAgent, Generic[OptionsCoT]):  # type: ignore[misc]
             "input_messages": input_messages,
             "session_messages": session_messages,
             "agent_name": agent_name,
-            "suppress_response_id": bool(per_service_call_history_providers),
+            "suppress_response_id": bool(per_service_call_history_providers) and not service_stores_history,
             "chat_options": co,
             "compaction_strategy": compaction_strategy or self.compaction_strategy,
             "tokenizer": tokenizer or self.tokenizer,
@@ -1413,11 +1460,15 @@ class RawAgent(BaseAgent, Generic[OptionsCoT]):  # type: ignore[misc]
             options=options or {},
         )
 
+        # When per-service-call persistence is enabled, the per-service-call middleware owns
+        # HistoryProvider loading (it loads locally when the service does not store history, or
+        # relies on the service when it does), so skip them on the once-per-run before_run path.
         per_service_call_history_required = self.require_per_service_call_history_persistence and bool(
             self._get_history_providers()
         )
 
-        # Run before_run providers (forward order, skip HistoryProvider when per-service-call persistence owns history)
+        # Run before_run providers (forward order, skip HistoryProvider when per-service-call
+        # persistence owns loading)
         for provider in self.context_providers:
             if per_service_call_history_required and isinstance(provider, HistoryProvider):
                 continue

python/packages/core/agent_framework/_clients.py

@@ -604,10 +604,13 @@ class BaseChatClient(SerializationMixin, ABC, Generic[OptionsCoT]):
                 and dict literals are accepted without specialized option typing.
             context_providers: Context providers to include during agent invocation.
             middleware: List of middleware to intercept agent and function invocations.
-            require_per_service_call_history_persistence: Whether to require per-service-call
-                chat history persistence. When enabled, history providers are invoked around
-                each model call instead of once per ``run()`` when the service is not already
-                storing history.
+            require_per_service_call_history_persistence: When enabled (and a HistoryProvider is
+                present), the provider always persists history after each model call. If the
+                client does not store history server-side, history providers are also loaded and
+                injected around each model call; if it does, provider loading is skipped and the
+                service-managed conversation is the source of truth (persistence still happens
+                after each model call). When no HistoryProvider is present, this flag has no
+                effect (no middleware is installed and nothing is persisted).
             function_invocation_configuration: Optional function invocation configuration override.
             compaction_strategy: Optional agent-level compaction override. When omitted,
                 client-level compaction defaults remain in effect for each call.

python/packages/core/agent_framework/_mcp.py

@@ -70,6 +70,31 @@ class MCPSpecificApproval(TypedDict, total=False):
 
 _MCP_REMOTE_NAME_KEY = "_mcp_remote_name"
 _MCP_NORMALIZED_NAME_KEY = "_mcp_normalized_name"
+# Reserved key in an ``additional_tool_argument_names`` mapping that applies its
+# values to every tool on the server rather than a single named tool.
+_MCP_GLOBAL_EXTRA_ARGS_KEY = "*"
+# Framework kwargs that flow through the function-invocation pipeline (via
+# ``FunctionInvocationContext.kwargs``) but must never be forwarded to an MCP
+# server: they are internal objects that the MCP SDK cannot serialize. They are
+# dropped as a safety net when a tool declares one of them in its schema, unless
+# the user explicitly opts the name back in via ``additional_tool_argument_names``
+# (explicit extras always win over the denylist).
+# - chat_options/tools/tool_choice/session/thread: framework runtime objects.
+# - conversation_id: internal tracking ID used by services like Azure AI.
+# - options: metadata/store used by AG-UI for Azure AI client requirements.
+# - response_format: a Pydantic model class for structured output (not serializable).
+# - _meta: reserved key extracted separately as MCP request metadata.
+_MCP_FRAMEWORK_DENYLIST: frozenset[str] = frozenset({
+    "chat_options",
+    "tools",
+    "tool_choice",
+    "session",
+    "thread",
+    "conversation_id",
+    "options",
+    "response_format",
+    "_meta",
+})
 _mcp_call_headers: contextvars.ContextVar[dict[str, str]] = contextvars.ContextVar("_mcp_call_headers")
 MCP_DEFAULT_TIMEOUT = 30
 MCP_DEFAULT_SSE_READ_TIMEOUT = 60 * 5
@@ -135,6 +160,34 @@ def _build_prefixed_mcp_name(
     return f"{normalized_prefix}_{trimmed_name}" if trimmed_name else normalized_prefix
 
 
+def _normalize_additional_tool_argument_names(
+    additional_tool_argument_names: Sequence[str] | Mapping[str, Sequence[str]] | None,
+) -> tuple[set[str], dict[str, set[str]]]:
+    """Split user-supplied extra argument names into global and per-tool sets.
+
+    Accepts either a sequence (applied to every tool) or a mapping keyed by remote
+    tool name, where the reserved key ``"*"`` is treated as global. Mapping values
+    may be a sequence or a single string. Returns a
+    ``(global_extras, per_tool_extras)`` tuple.
+    """
+    if additional_tool_argument_names is None:
+        return set(), {}
+    if isinstance(additional_tool_argument_names, str):
+        return {additional_tool_argument_names}, {}
+    if isinstance(additional_tool_argument_names, Mapping):
+        global_extras: set[str] = set()
+        per_tool_extras: dict[str, set[str]] = {}
+        for tool_name, names in additional_tool_argument_names.items():
+            # Treat a bare string value as a single name rather than iterating its characters.
+            names_set = {names} if isinstance(names, str) else set(names)
+            if tool_name == _MCP_GLOBAL_EXTRA_ARGS_KEY:
+                global_extras.update(names_set)
+            else:
+                per_tool_extras[tool_name] = names_set
+        return global_extras, per_tool_extras
+    return set(additional_tool_argument_names), {}
+
+
 def _inject_otel_into_mcp_meta(meta: dict[str, Any] | None = None) -> dict[str, Any] | None:
     """Inject OpenTelemetry trace context into MCP request _meta via the global propagator(s)."""
     carrier: dict[str, str] = {}
@@ -294,6 +347,7 @@ class MCPTool:
         client: SupportsChatGetResponse | None = None,
         additional_properties: dict[str, Any] | None = None,
         task_options: MCPTaskOptions | None = None,
+        additional_tool_argument_names: Sequence[str] | Mapping[str, Sequence[str]] | None = None,
     ) -> None:
         """Initialize the MCP Tool base.
 
@@ -328,6 +382,10 @@ class MCPTool:
             task_options: Options controlling how long-running MCP tasks are driven for
                 tools that advertise ``execution.taskSupport == "required"``. When ``None``,
                 the defaults from :class:`MCPTaskOptions` are used.
+            additional_tool_argument_names: Extra argument names to forward to the MCP server
+                in addition to each tool's declared parameters. A ``Sequence[str]`` applies to
+                every tool; a ``Mapping[str, Sequence[str]]`` is keyed by remote tool name with
+                ``"*"`` as a global key. See the transport subclasses for full details.
         """
         self.name = name
         self.description = description or ""
@@ -355,6 +413,10 @@ class MCPTool:
         self._functions: list[FunctionTool] = []
         self._tool_call_meta_by_name: dict[str, dict[str, Any]] = {}
         self._tool_task_support_by_name: dict[str, str] = {}
+        self._tool_param_names_by_name: dict[str, set[str]] = {}
+        self._global_extra_arg_names, self._tool_extra_arg_names = _normalize_additional_tool_argument_names(
+            additional_tool_argument_names
+        )
         self.is_connected: bool = False
         self._tools_loaded: bool = False
         self._prompts_loaded: bool = False
@@ -1229,6 +1291,7 @@ class MCPTool:
         existing_names = {func.name for func in self._functions}
         tool_call_meta_by_name: dict[str, dict[str, Any]] = {}
         tool_task_support_by_name: dict[str, str] = {}
+        tool_param_names_by_name: dict[str, set[str]] = {}
 
         params: types.PaginatedRequestParams | None = None
         while True:
@@ -1271,14 +1334,6 @@ class MCPTool:
                 if task_support is not None:
                     tool_task_support_by_name[tool.name] = task_support
 
-                normalized_name = _normalize_mcp_name(tool.name)
-                local_name = _build_prefixed_mcp_name(normalized_name, self.tool_name_prefix)
-
-                # Skip if already loaded
-                if local_name in existing_names:
-                    continue
-
-                approval_mode = self._determine_approval_mode(local_name, normalized_name, tool.name)
                 # Normalize inputSchema: ensure "properties" exists for object schemas.
                 # Some MCP servers (e.g. zero-argument tools) omit "properties",
                 # which causes OpenAI API to reject the schema with a 400 error.
@@ -1288,6 +1343,24 @@ class MCPTool:
                 if input_schema.get("type") == "object" and "properties" not in input_schema:
                     input_schema["properties"] = {}
 
+                # Register declared param names before the existing-tool skip below so that
+                # reloads (e.g. notifications/tools/list_changed) preserve the allowlist for
+                # tools that are already loaded, consistent with tool_call_meta_by_name and
+                # tool_task_support_by_name above.
+                schema_properties = input_schema.get("properties")
+                tool_param_names_by_name[tool.name] = (
+                    set(cast(dict[str, Any], schema_properties)) if isinstance(schema_properties, dict) else set()
+                )
+
+                normalized_name = _normalize_mcp_name(tool.name)
+                local_name = _build_prefixed_mcp_name(normalized_name, self.tool_name_prefix)
+
+                # Skip if already loaded
+                if local_name in existing_names:
+                    continue
+
+                approval_mode = self._determine_approval_mode(local_name, normalized_name, tool.name)
+
                 async def _call_tool_with_runtime_kwargs(
                     ctx: FunctionInvocationContext,
                     *,
@@ -1320,6 +1393,7 @@ class MCPTool:
 
         self._tool_call_meta_by_name = tool_call_meta_by_name
         self._tool_task_support_by_name = tool_task_support_by_name
+        self._tool_param_names_by_name = tool_param_names_by_name
 
     async def _close_on_owner(self) -> None:
         # Cancel any pending reload tasks before tearing down the session.
@@ -1530,10 +1604,14 @@ class MCPTool:
                 raise ToolExecutionException(f"Failed to call tool '{tool_name}'.", inner_exception=ex) from ex
         raise ToolExecutionException(f"Failed to call tool '{tool_name}' after retries.")
 
+    def _resolved_extra_args(self, tool_name: str) -> set[str]:
+        """Return the user-configured extra argument names allowed for a tool."""
+        return self._global_extra_arg_names | self._tool_extra_arg_names.get(tool_name, set())
+
     def _prepare_call_kwargs(
         self, tool_name: str, kwargs: dict[str, Any]
     ) -> tuple[dict[str, Any], dict[str, Any] | None]:
-        """Filter framework-only kwargs and build the merged MCP request metadata."""
+        """Filter kwargs down to the tool's arguments and build the merged MCP request metadata."""
         raw_user_meta: object | None = kwargs.get("_meta")
         user_meta: dict[str, Any] | None = None
         if raw_user_meta is not None and not isinstance(raw_user_meta, dict):
@@ -1546,27 +1624,28 @@ class MCPTool:
                     raise ToolExecutionException("MCP tool metadata provided via _meta must use string keys.")
                 user_meta[key] = value
 
-        # Filter out framework kwargs that cannot be serialized by the MCP SDK.
-        # These are internal objects passed through the function invocation pipeline
-        # that should not be forwarded to external MCP servers.
-        # conversation_id is an internal tracking ID used by services like Azure AI.
-        # options contains metadata/store used by AG-UI for Azure AI client requirements.
-        # response_format is a Pydantic model class used for structured output (not serializable).
+        # Allowlist: forward only the tool's declared parameters (from inputSchema.properties)
+        # plus any user-configured extra argument names. Everything else - notably the
+        # framework runtime kwargs injected through the function-invocation pipeline - is
+        # stripped so it is never forwarded to the MCP server. Tools that declare no usable
+        # properties forward only the user-configured extras.
+        #
+        # The extra names come exclusively from additional_tool_argument_names, which is set in
+        # user code at construction time; there is no per-call override, so a model-issued tool
+        # call cannot change which names are allowed through.
+        #
+        # The framework denylist acts as a safety net for keys a server *declares* in its
+        # schema that collide with internal, non-serializable framework objects (e.g. a tool
+        # that declares a parameter literally named "thread"): such declared-but-denylisted
+        # keys are dropped. Names the user explicitly opts in via additional_tool_argument_names
+        # always win. The reserved _meta key is handled separately above and never forwarded as
+        # an argument.
+        declared = self._tool_param_names_by_name.get(tool_name, set())
+        extras = self._resolved_extra_args(tool_name)
         filtered_kwargs = {
             k: v
             for k, v in kwargs.items()
-            if k
-            not in {
-                "chat_options",
-                "tools",
-                "tool_choice",
-                "session",
-                "thread",
-                "conversation_id",
-                "options",
-                "response_format",
-                "_meta",
-            }
+            if k != "_meta" and (k in extras or (k in declared and k not in _MCP_FRAMEWORK_DENYLIST))
         }
 
         # Some MCP proxies require their tools/list metadata to be echoed on tools/call.
@@ -1643,9 +1722,7 @@ class MCPTool:
             return parser(fallback_result)
 
         if task_id is None:
-            raise ToolExecutionException(
-                f"MCP server did not return a task_id or fallback result for '{tool_name}'."
-            )
+            raise ToolExecutionException(f"MCP server did not return a task_id or fallback result for '{tool_name}'.")
 
         # Track to completion: poll until terminal, then fetch payload. Never re-issue
         # tools/call past this point; reconnect-and-retry only against the same task_id.
@@ -1765,9 +1842,7 @@ class MCPTool:
         transient_codes: frozenset[int] = frozenset({int(httpx.codes.REQUEST_TIMEOUT)})
 
         while True:
-            request = types.ClientRequest(
-                types.GetTaskRequest(params=types.GetTaskRequestParams(taskId=task_id))
-            )
+            request = types.ClientRequest(types.GetTaskRequest(params=types.GetTaskRequestParams(taskId=task_id)))
             try:
                 # GetTaskResult.ttl is required-but-Optional in the SDK; coerce below.
                 lenient = await self._send_with_one_reconnect(
@@ -1775,9 +1850,7 @@ class MCPTool:
                 )
             except McpError as ex:
                 if ex.error.code in transient_codes:
-                    logger.debug(
-                        "Transient %s on tasks/get for '%s'; will retry.", ex.error.code, task_id
-                    )
+                    logger.debug("Transient %s on tasks/get for '%s'; will retry.", ex.error.code, task_id)
                     await asyncio.sleep(_MCP_TASK_MIN_POLL_INTERVAL.total_seconds())
                     continue
                 # Hard server error mid-poll: task may still be running.
@@ -1906,9 +1979,7 @@ class MCPTool:
                 if not self._is_connection_lost(ex):
                     raise
                 if attempt < _MCP_RECONNECT_ATTEMPTS - 1:
-                    logger.info(
-                        "MCP connection lost during %s; reconnecting (task_id=%s).", operation, task_id
-                    )
+                    logger.info("MCP connection lost during %s; reconnecting (task_id=%s).", operation, task_id)
                     try:
                         await self.connect(reset=True)
                     except Exception as reconn_ex:
@@ -1967,9 +2038,7 @@ class MCPTool:
         """
         from mcp import types
 
-        request = types.ClientRequest(
-            types.CancelTaskRequest(params=types.CancelTaskRequestParams(taskId=task_id))
-        )
+        request = types.ClientRequest(types.CancelTaskRequest(params=types.CancelTaskRequestParams(taskId=task_id)))
         try:
             await asyncio.wait_for(
                 self.session.send_request(request, types.CancelTaskResult),  # type: ignore[union-attr]
@@ -1979,8 +2048,7 @@ class MCPTool:
             raise
         except asyncio.TimeoutError:
             logger.warning(
-                "Best-effort tasks/cancel for '%s' timed out after %.1fs; "
-                "remote task may still be running.",
+                "Best-effort tasks/cancel for '%s' timed out after %.1fs; remote task may still be running.",
                 task_id,
                 _MCP_TASK_CANCEL_TIMEOUT.total_seconds(),
             )
@@ -2153,6 +2221,7 @@ class MCPStdioTool(MCPTool):
         client: SupportsChatGetResponse | None = None,
         additional_properties: dict[str, Any] | None = None,
         task_options: MCPTaskOptions | None = None,
+        additional_tool_argument_names: Sequence[str] | Mapping[str, Sequence[str]] | None = None,
         **kwargs: Any,
     ) -> None:
         """Initialize the MCP stdio tool.
@@ -2199,6 +2268,20 @@ class MCPStdioTool(MCPTool):
             client: The chat client to use for sampling.
             task_options: Options for tools that advertise
                 ``execution.taskSupport == "required"``. See :class:`MCPTaskOptions`.
+            additional_tool_argument_names: Extra argument names to forward to the MCP server in
+                addition to each tool's declared parameters (from its ``inputSchema.properties``).
+                By default only declared parameters are sent; framework runtime kwargs injected
+                through the function-invocation pipeline are stripped. Use this to opt specific
+                keys back in. Accepts either a ``Sequence[str]`` applied to every tool, or a
+                ``Mapping[str, Sequence[str]]`` keyed by remote tool name where the reserved key
+                ``"*"`` applies to every tool. This is configured only here in user code; there is
+                no per-call override, so a model-issued tool call cannot change which names pass
+                through. To use a server that accepts ``additionalProperties: true``, list the
+                extra names here and then either (1) manually extend that tool's ``inputSchema``
+                (via the ``.functions`` list after connecting) so the model is prompted to supply
+                them, or (2) supply the values yourself through ``function_invocation_kwargs``. If
+                a name is supplied via both the model and ``function_invocation_kwargs``, the
+                model-supplied value wins.
             kwargs: Any extra arguments to pass to the stdio client.
         """
         super().__init__(
@@ -2216,6 +2299,7 @@ class MCPStdioTool(MCPTool):
             parse_prompt_results=parse_prompt_results,
             request_timeout=request_timeout,
             task_options=task_options,
+            additional_tool_argument_names=additional_tool_argument_names,
         )
         self.command = command
         self.args = args or []
@@ -2295,6 +2379,7 @@ class MCPStreamableHTTPTool(MCPTool):
         http_client: AsyncClient | None = None,
         header_provider: Callable[[dict[str, Any]], dict[str, str]] | None = None,
         task_options: MCPTaskOptions | None = None,
+        additional_tool_argument_names: Sequence[str] | Mapping[str, Sequence[str]] | None = None,
         **kwargs: Any,
     ) -> None:
         """Initialize the MCP streamable HTTP tool.
@@ -2349,6 +2434,20 @@ class MCPStreamableHTTPTool(MCPTool):
                 agent middleware) without creating a separate ``httpx.AsyncClient``.
             task_options: Options for tools that advertise
                 ``execution.taskSupport == "required"``. See :class:`MCPTaskOptions`.
+            additional_tool_argument_names: Extra argument names to forward to the MCP server in
+                addition to each tool's declared parameters (from its ``inputSchema.properties``).
+                By default only declared parameters are sent; framework runtime kwargs injected
+                through the function-invocation pipeline are stripped. Use this to opt specific
+                keys back in. Accepts either a ``Sequence[str]`` applied to every tool, or a
+                ``Mapping[str, Sequence[str]]`` keyed by remote tool name where the reserved key
+                ``"*"`` applies to every tool. This is configured only here in user code; there is
+                no per-call override, so a model-issued tool call cannot change which names pass
+                through. To use a server that accepts ``additionalProperties: true``, list the
+                extra names here and then either (1) manually extend that tool's ``inputSchema``
+                (via the ``.functions`` list after connecting) so the model is prompted to supply
+                them, or (2) supply the values yourself through ``function_invocation_kwargs``. If
+                a name is supplied via both the model and ``function_invocation_kwargs``, the
+                model-supplied value wins.
             kwargs: Additional keyword arguments (accepted for backward compatibility but not used).
         """
         super().__init__(
@@ -2366,6 +2465,7 @@ class MCPStreamableHTTPTool(MCPTool):
             parse_prompt_results=parse_prompt_results,
             request_timeout=request_timeout,
             task_options=task_options,
+            additional_tool_argument_names=additional_tool_argument_names,
         )
         self.url = url
         self.terminate_on_close = terminate_on_close
@@ -2492,6 +2592,7 @@ class MCPWebsocketTool(MCPTool):
         client: SupportsChatGetResponse | None = None,
         additional_properties: dict[str, Any] | None = None,
         task_options: MCPTaskOptions | None = None,
+        additional_tool_argument_names: Sequence[str] | Mapping[str, Sequence[str]] | None = None,
         **kwargs: Any,
     ) -> None:
         """Initialize the MCP WebSocket tool.
@@ -2536,6 +2637,20 @@ class MCPWebsocketTool(MCPTool):
             client: The chat client to use for sampling.
             task_options: Options for tools that advertise
                 ``execution.taskSupport == "required"``. See :class:`MCPTaskOptions`.
+            additional_tool_argument_names: Extra argument names to forward to the MCP server in
+                addition to each tool's declared parameters (from its ``inputSchema.properties``).
+                By default only declared parameters are sent; framework runtime kwargs injected
+                through the function-invocation pipeline are stripped. Use this to opt specific
+                keys back in. Accepts either a ``Sequence[str]`` applied to every tool, or a
+                ``Mapping[str, Sequence[str]]`` keyed by remote tool name where the reserved key
+                ``"*"`` applies to every tool. This is configured only here in user code; there is
+                no per-call override, so a model-issued tool call cannot change which names pass
+                through. To use a server that accepts ``additionalProperties: true``, list the
+                extra names here and then either (1) manually extend that tool's ``inputSchema``
+                (via the ``.functions`` list after connecting) so the model is prompted to supply
+                them, or (2) supply the values yourself through ``function_invocation_kwargs``. If
+                a name is supplied via both the model and ``function_invocation_kwargs``, the
+                model-supplied value wins.
             kwargs: Any extra arguments to pass to the WebSocket client.
         """
         super().__init__(
@@ -2553,6 +2668,7 @@ class MCPWebsocketTool(MCPTool):
             parse_prompt_results=parse_prompt_results,
             request_timeout=request_timeout,
             task_options=task_options,
+            additional_tool_argument_names=additional_tool_argument_names,
         )
         self.url = url
         self._client_kwargs = kwargs

python/packages/core/agent_framework/_sessions.py

@@ -16,6 +16,7 @@ from __future__ import annotations
 import asyncio
 import copy
 import json
+import logging
 import threading
 import uuid
 import weakref
@@ -36,6 +37,8 @@ if TYPE_CHECKING:
     from ._middleware import MiddlewareTypes
 
 
+logger = logging.getLogger("agent_framework")
+
 # Registry of known types for state deserialization
 _STATE_TYPE_REGISTRY: dict[str, type] = {}
 
@@ -580,6 +583,7 @@ class PerServiceCallHistoryPersistingMiddleware(ChatMiddleware):
         agent: SupportsAgentRun,
         session: AgentSession,
         providers: Sequence[HistoryProvider],
+        service_stores_history: bool = False,
     ) -> None:
         """Initialize the middleware.
 
@@ -587,10 +591,16 @@ class PerServiceCallHistoryPersistingMiddleware(ChatMiddleware):
             agent: The agent that owns the history providers.
             session: The active session for the current run.
             providers: The history providers participating in per-service-call persistence.
+            service_stores_history: When True, the chat client stores history server-side. The
+                middleware then skips loading providers and leaves the real conversation id
+                untouched, persisting each service call without driving the function loop with a
+                local sentinel. When False, the middleware loads providers and uses a local
+                sentinel conversation id so the function loop runs without service-side storage.
         """
         self._agent = agent
         self._session = session
         self._providers = list(providers)
+        self._service_stores_history = service_stores_history
 
     async def _prepare_service_call_context(self, messages: Sequence[Message]) -> SessionContext:
         """Create a per-call SessionContext and load history providers into it."""
@@ -602,6 +612,9 @@ class PerServiceCallHistoryPersistingMiddleware(ChatMiddleware):
         )
         for source_id, source_messages in context_messages.items():
             service_call_context.extend_messages(source_id, source_messages)
+        # When the service stores history, it owns loading; the providers are write-only sinks.
+        if self._service_stores_history:
+            return service_call_context
         for provider in self._providers:
             if not provider.load_messages:
                 continue
@@ -652,17 +665,35 @@ class PerServiceCallHistoryPersistingMiddleware(ChatMiddleware):
         response: ChatResponse,
     ) -> ChatResponse:
         """Persist a model response and apply the local follow-up sentinel when needed."""
-        if response.conversation_id is not None and not is_local_history_conversation_id(response.conversation_id):
+        if (
+            not self._service_stores_history
+            and response.conversation_id is not None
+            and not is_local_history_conversation_id(response.conversation_id)
+        ):
             raise ChatClientInvalidResponseException(
                 "require_per_service_call_history_persistence cannot be used "
                 "when the chat client returns a real conversation_id."
             )
 
+        # In storing mode the service is expected to echo a conversation id that the next run
+        # resumes from. If it comes back empty, the provider still captures this turn but there is
+        # no service id to load from next time, so cross-turn history can be lost silently. Warn
+        # every time so this uncommon, easy-to-miss failure mode cannot fail quietly.
+        if self._service_stores_history and response.conversation_id is None:
+            logger.warning(
+                "require_per_service_call_history_persistence is enabled with a chat client that "
+                "stores history server-side, but the client returned no conversation_id; cross-turn "
+                "history may not resume. Set store=False to load and resume from the HistoryProvider "
+                "instead."
+            )
+
         await self._persist_service_call_response(
             service_call_context=service_call_context,
             response=response,
         )
-        if _response_contains_follow_up_request(response):
+        # The local sentinel only applies when the service does not store history; when it does,
+        # the real conversation id already drives function-loop continuation.
+        if not self._service_stores_history and _response_contains_follow_up_request(response):
             response.mark_internal_conversation_id()
             response.conversation_id = LOCAL_HISTORY_CONVERSATION_ID
         return response
@@ -681,8 +712,12 @@ class PerServiceCallHistoryPersistingMiddleware(ChatMiddleware):
                 result type for streaming or non-streaming execution.
         """
         service_call_context = await self._prepare_service_call_context(context.messages)
-        context.messages = service_call_context.get_messages(include_input=True)
-        self._strip_local_conversation_id(context)
+        # When the service stores history, leave the outgoing messages and the real conversation
+        # id untouched (pass-through); the middleware only persists. Otherwise reconstruct the
+        # outgoing messages from the loaded local history and strip the local sentinel.
+        if not self._service_stores_history:
+            context.messages = service_call_context.get_messages(include_input=True)
+            self._strip_local_conversation_id(context)
 
         await call_next()
 

python/packages/core/agent_framework/_workflows/_checkpoint_encoding.py

@@ -13,6 +13,35 @@ during deserialization.  The default built-in safe set covers common Python
 value types (primitives, datetime, uuid, ...), all ``agent_framework`` internal
 types, and all ``openai.types`` types.  Callers can extend the set by passing
 additional ``"module:qualname"`` strings.
+
+Security Model
+--------------
+Checkpoint storage is treated as a **trusted data source**.  The serialization
+format uses Python's ``pickle`` module which can execute arbitrary code during
+deserialization.  The ``RestrictedUnpickler`` provides a defense-in-depth
+allowlist that limits instantiable classes, but it is **not** a security
+boundary — certain allowlisted builtins (e.g. ``getattr``) are required for
+legitimate object reconstruction (enums, named tuples) and cannot be removed
+without breaking compatibility.
+
+Developers **must** ensure that:
+
+1. The checkpoint storage backend (file system, Cosmos DB, Azure Blob, Durable
+   Functions storage) is access-controlled and not writable by untrusted
+   parties.
+2. Data flowing into ``decode_checkpoint_value`` originates exclusively from
+   the application's own checkpoint storage — never from user-supplied HTTP
+   requests, message payloads, or other untrusted sources.
+3. The ``allowed_types`` parameter is specified whenever possible to restrict
+   the set of reconstructible types to the minimum required by the application.
+4. Never pass untrusted external input to ``decode_checkpoint_value``. If you
+   must accept external JSON that might contain checkpoint markers, sanitize it
+   first (for example, :func:`agent_framework_azurefunctions._serialization.strip_pickle_markers`).
+
+The allowlist is a mitigation that reduces attack surface but does not
+eliminate the inherent risks of deserializing untrusted pickle data.  Treat
+your checkpoint storage with the same access controls you would apply to
+application secrets or database credentials.
 """
 
 from __future__ import annotations

python/packages/core/pyproject.toml

@@ -4,7 +4,7 @@ description = "Microsoft Agent Framework for building AI Agents with Python. Thi
 authors = [{ name = "Microsoft", email = "af-support@microsoft.com"}]
 readme = "README.md"
 requires-python = ">=3.10"
-version = "1.8.0"
+version = "1.8.1"
 license-files = ["LICENSE"]
 urls.homepage = "https://aka.ms/agent-framework"
 urls.source = "https://github.com/microsoft/agent-framework/tree/main/python"

python/packages/core/tests/core/test_agents.py

@@ -3,6 +3,7 @@
 import contextlib
 import inspect
 import json
+import logging
 from collections.abc import AsyncIterable, Awaitable, Callable, MutableSequence, Sequence
 from typing import Any, cast
 from unittest.mock import AsyncMock, MagicMock, patch
@@ -42,6 +43,8 @@ from agent_framework._mcp import MCPTool, _build_prefixed_mcp_name, _normalize_m
 from agent_framework._middleware import FunctionInvocationContext
 from agent_framework.exceptions import AgentInvalidRequestException, ChatClientInvalidResponseException
 
+from .conftest import MockBaseChatClient
+
 
 class _FixedTokenizer:
     def __init__(self, token_count: int) -> None:
@@ -609,6 +612,7 @@ async def test_streaming_per_service_call_persistence_hides_response_id_from_aft
 
 async def test_per_service_call_persistence_uses_real_service_storage_when_client_stores_by_default(
     chat_client_base: SupportsChatGetResponse,
+    caplog: pytest.LogCaptureFixture,
 ) -> None:
     provider = _RecordingHistoryProvider()
 
@@ -649,15 +653,22 @@ async def test_per_service_call_persistence_uses_real_service_storage_when_clien
         require_per_service_call_history_persistence=True,
     )
 
-    result = await agent.run("What's the weather in Seattle?", session=session)
+    with caplog.at_level(logging.WARNING, logger="agent_framework"):
+        result = await agent.run("What's the weather in Seattle?", session=session)
 
     provider_state = session.state[provider.source_id]
 
     assert result.text == "It is sunny in Seattle."
     assert result.response_id == "resp_call_2"
     assert chat_client_base.call_count == 2
+    # The service owns the conversation, so the provider never loads (issue #5798).
     assert "get_call_count" not in provider_state
-    assert "save_call_count" not in provider_state
+    # Persistence is owned by the per-service-call middleware: it persists once per service call
+    # (issue #5798: the provider must never be silently bypassed when the service stores history).
+    # This run makes two service calls (function call + final answer), so it persists twice.
+    assert provider_state["save_call_count"] == 2
+    # load_messages=True while the service stores history surfaces a warning.
+    assert any("load_messages" in record.message for record in caplog.records)
     assert session.service_session_id == "resp_service_managed"
 
 
@@ -1996,6 +2007,19 @@ def test_merge_options_none_values_ignored():
     assert result["key2"] == "value2"
 
 
+def test_merge_options_drops_none_base_values():
+    """Test _merge_options strips None values so unset options are never forwarded."""
+    base = {"store": None, "temperature": 0.5}
+    override = {"top_p": 0.9}
+
+    result = _merge_options(base, override)
+
+    # An unset base value (e.g. store=None from default_options) must not survive the merge.
+    assert "store" not in result
+    assert result["temperature"] == 0.5
+    assert result["top_p"] == 0.9
+
+
 def test_merge_options_runtime_model_overrides_default_model() -> None:
     """Test _merge_options lets a runtime model override a default model."""
     result = _merge_options({"model": "default-model"}, {"model": "runtime-model"})
@@ -2658,3 +2682,449 @@ async def test_as_tool_raises_on_user_input_request(client: SupportsChatGetRespo
     assert len(exc_info.value.contents) == 1
     assert exc_info.value.contents[0].type == "oauth_consent_request"
     assert exc_info.value.contents[0].consent_link == "https://login.microsoftonline.com/consent"
+
+
+# region Per-service-call history persistence scenario matrix
+#
+# The driving field is ``require_per_service_call_history_persistence``. Every scenario runs a
+# single agent run that makes **two service calls** -- a function call followed by a final
+# completion -- so the *timing* of persistence is observable:
+#
+# * When the flag is ``True``, the per-service-call middleware persists the provider **after each
+#   service call**. So the function-call turn is already saved by the time the second (final)
+#   service call starts. This holds regardless of whether the chat client stores history
+#   server-side (the bug in issue #5798 was that a storing client silently bypassed persistence).
+# * When the flag is ``False``, the provider persists **once, at the end of the run** -- nothing is
+#   saved between the two service calls.
+#
+# ``SpyChatClient.saves_before_call`` records ``provider.save_calls`` at the start of every service
+# call, so ``[0, 1]`` means "the function-call turn was persisted before the final call" and
+# ``[0, 0]`` means "no persistence happened mid-run". The client's ``store`` / ``STORES_BY_DEFAULT``
+# only selects *how* the middleware behaves -- never *whether* the provider persists.
+
+_PSC_SERVICE_CONVERSATION_ID = "svc-conversation"
+
+_psc_stream_params = pytest.mark.parametrize("stream", [False, True], ids=["sync", "stream"])
+
+
+@tool(name="lookup_weather", approval_mode="never_require")
+def _psc_lookup_weather(location: str) -> str:
+    return f"Weather in {location}: sunny"
+
+
+def _psc_function_call_script() -> list[tuple[str, ...]]:
+    """A fresh function-call-then-final-completion script (the client mutates it)."""
+    return [
+        ("call", "call_1", "lookup_weather", '{"location": "Seattle"}'),
+        ("text", "It is sunny in Seattle."),
+    ]
+
+
+class _PscSpyHistoryProvider(HistoryProvider):
+    """In-memory history provider that records load/save calls for assertions."""
+
+    def __init__(self, source_id: str = "spy_history", **kwargs: Any) -> None:
+        super().__init__(source_id, **kwargs)
+        self._messages: list[Message] = []
+        self.get_calls: int = 0
+        self.save_calls: int = 0
+        self.saved_batches: list[list[Message]] = []
+
+    async def get_messages(
+        self, session_id: str | None, *, state: dict[str, Any] | None = None, **kwargs: Any
+    ) -> list[Message]:
+        self.get_calls += 1
+        return list(self._messages)
+
+    async def save_messages(
+        self,
+        session_id: str | None,
+        messages: Sequence[Message],
+        *,
+        state: dict[str, Any] | None = None,
+        **kwargs: Any,
+    ) -> None:
+        self.save_calls += 1
+        self.saved_batches.append(list(messages))
+        self._messages.extend(messages)
+
+    @property
+    def stored_messages(self) -> list[Message]:
+        return list(self._messages)
+
+
+class _PscSpyChatClient(MockBaseChatClient):
+    """Chat client that scripts a function-call/final-completion sequence.
+
+    It records, at the start of each service call, how many provider saves have already happened
+    (``saves_before_call``), what messages it received, and what options it saw. When the effective
+    ``store`` is truthy it returns a stable ``conversation_id`` to mimic a server-managed
+    conversation, so the framework propagates ``session.service_session_id``.
+    """
+
+    def __init__(
+        self,
+        *,
+        provider: _PscSpyHistoryProvider,
+        stores_by_default: bool = False,
+        script: list[tuple[str, ...]] | None = None,
+        echo_conversation_id: bool = True,
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(**kwargs)
+        self.STORES_BY_DEFAULT = stores_by_default  # type: ignore[attr-defined]
+        self._provider = provider
+        self._script = list(script) if script is not None else [("text", "ok")]
+        self._echo_conversation_id = echo_conversation_id
+        self.received_messages: list[list[Message]] = []
+        self.received_options: list[dict[str, Any]] = []
+        self.saves_before_call: list[int] = []
+
+    def _effective_store(self, options: dict[str, Any]) -> bool:
+        store = options.get("store")
+        if store is None:
+            return bool(self.STORES_BY_DEFAULT)
+        return bool(store)
+
+    def _next_contents(self) -> list[Content]:
+        turn = self._script.pop(0) if self._script else ("text", "ok")
+        if turn[0] == "call":
+            _, call_id, name, args = turn
+            return [Content.from_function_call(call_id=call_id, name=name, arguments=args)]
+        return [Content.from_text(turn[1])]
+
+    def _inner_get_response(  # type: ignore[override]
+        self,
+        *,
+        messages: MutableSequence[Message],
+        stream: bool,
+        options: dict[str, Any],
+        **kwargs: Any,
+    ) -> Awaitable[ChatResponse] | ResponseStream[ChatResponseUpdate, ChatResponse]:
+        self.received_messages.append(list(messages))
+        self.received_options.append(dict(options))
+        self.saves_before_call.append(self._provider.save_calls)
+        store_and_echo = self._effective_store(options) and self._echo_conversation_id
+        conv_id = _PSC_SERVICE_CONVERSATION_ID if store_and_echo else None
+        contents = self._next_contents()
+
+        if stream:
+
+            async def _stream() -> AsyncIterable[ChatResponseUpdate]:
+                self.call_count += 1
+                yield ChatResponseUpdate(
+                    contents=contents,
+                    role="assistant",
+                    finish_reason="stop",
+                    conversation_id=conv_id,
+                )
+
+            def _finalize(updates: Sequence[ChatResponseUpdate]) -> ChatResponse:
+                response = ChatResponse.from_updates(updates, output_format_type=options.get("response_format"))
+                if conv_id:
+                    response.conversation_id = conv_id
+                return response
+
+            return ResponseStream(_stream(), finalizer=_finalize)
+
+        async def _get() -> ChatResponse:
+            self.call_count += 1
+            return ChatResponse(
+                messages=Message(role="assistant", contents=contents),
+                conversation_id=conv_id,
+            )
+
+        return _get()
+
+
+def _psc_build_agent(
+    client: _PscSpyChatClient,
+    provider: _PscSpyHistoryProvider,
+    *,
+    require_per_service_call_history_persistence: bool,
+    default_options: dict[str, Any] | None = None,
+) -> Agent:
+    kwargs: dict[str, Any] = {}
+    if default_options is not None:
+        kwargs["default_options"] = default_options
+    return Agent(
+        client=client,
+        tools=[_psc_lookup_weather],
+        context_providers=[provider],
+        require_per_service_call_history_persistence=require_per_service_call_history_persistence,
+        **kwargs,
+    )
+
+
+async def _psc_run(agent: Agent, text: str, session: AgentSession, *, stream: bool) -> str:
+    if stream:
+        chunks: list[str] = []
+        async for update in agent.run(text, session=session, stream=True):
+            chunks.append(update.text or "")
+        return "".join(chunks)
+    result = await agent.run(text, session=session)
+    return result.text
+
+
+# driver=True (the contract under test): persistence happens per service call
+
+
+@_psc_stream_params
+async def test_psc_flag_on_store_false_persists_after_each_service_call(stream: bool) -> None:
+    """Mode A (flag on, service does not store): function-call turn is persisted before the final call."""
+    provider = _PscSpyHistoryProvider()
+    client = _PscSpyChatClient(provider=provider, stores_by_default=False, script=_psc_function_call_script())
+    agent = _psc_build_agent(client, provider, require_per_service_call_history_persistence=True)
+    session = agent.create_session()
+
+    text = await _psc_run(agent, "What's the weather in Seattle?", session, stream=stream)
+
+    assert text == "It is sunny in Seattle."
+    # Two service calls: function call, then final completion.
+    assert client.call_count == 2
+    # The contract: the function-call turn was persisted *before* the second service call started.
+    assert client.saves_before_call == [0, 1]
+    assert provider.save_calls == 2
+    # Mode A loads local history (the middleware injects it before each service call).
+    assert provider.get_calls >= 1
+    # No service-side storage, so no conversation id is propagated.
+    assert session.service_session_id is None
+
+
+@_psc_stream_params
+async def test_psc_flag_on_stores_by_default_persists_after_each_service_call(
+    stream: bool, caplog: pytest.LogCaptureFixture
+) -> None:
+    """Mode B (flag on, service stores by default): still persists per service call, but skips load (issue #5798)."""
+    provider = _PscSpyHistoryProvider()  # load_messages=True by default
+    client = _PscSpyChatClient(provider=provider, stores_by_default=True, script=_psc_function_call_script())
+    agent = _psc_build_agent(client, provider, require_per_service_call_history_persistence=True)
+    session = agent.create_session()
+
+    with caplog.at_level(logging.WARNING, logger="agent_framework"):
+        text = await _psc_run(agent, "What's the weather in Seattle?", session, stream=stream)
+
+    assert text == "It is sunny in Seattle."
+    assert client.call_count == 2
+    # The invariant the bug violated: persistence still happens per service call when the service stores.
+    assert client.saves_before_call == [0, 1]
+    assert provider.save_calls == 2
+    # The service owns loading, so the provider is never asked to load.
+    assert provider.get_calls == 0
+    # A warning surfaces the bypassed load (load_messages=True).
+    assert any("load_messages" in record.message for record in caplog.records)
+    # The real service conversation id propagates to the session.
+    assert session.service_session_id == _PSC_SERVICE_CONVERSATION_ID
+
+
+@_psc_stream_params
+async def test_psc_flag_on_store_only_provider_no_load_no_warning(
+    stream: bool, caplog: pytest.LogCaptureFixture
+) -> None:
+    """Mode B with a store-only provider (load_messages=False): persists per call, no load, no warning."""
+    provider = _PscSpyHistoryProvider(load_messages=False)
+    client = _PscSpyChatClient(provider=provider, stores_by_default=True, script=_psc_function_call_script())
+    agent = _psc_build_agent(client, provider, require_per_service_call_history_persistence=True)
+    session = agent.create_session()
+
+    with caplog.at_level(logging.WARNING, logger="agent_framework"):
+        await _psc_run(agent, "What's the weather in Seattle?", session, stream=stream)
+
+    assert client.saves_before_call == [0, 1]
+    assert provider.save_calls == 2
+    assert provider.get_calls == 0
+    assert not any("load_messages" in record.message for record in caplog.records)
+
+
+@_psc_stream_params
+async def test_psc_flag_on_store_false_override_behaves_as_mode_a(stream: bool) -> None:
+    """Flag on + storing client but store=False override: falls back to Mode A (local, per call)."""
+    provider = _PscSpyHistoryProvider()
+    client = _PscSpyChatClient(provider=provider, stores_by_default=True, script=_psc_function_call_script())
+    agent = _psc_build_agent(
+        client, provider, require_per_service_call_history_persistence=True, default_options={"store": False}
+    )
+    session = agent.create_session()
+
+    await _psc_run(agent, "What's the weather in Seattle?", session, stream=stream)
+
+    assert client.saves_before_call == [0, 1]
+    assert provider.save_calls == 2
+    assert provider.get_calls >= 1
+    # store=False forces local handling, so no real service conversation id.
+    assert session.service_session_id is None
+
+
+@_psc_stream_params
+async def test_psc_flag_on_store_none_treated_as_absent(stream: bool, caplog: pytest.LogCaptureFixture) -> None:
+    """Flag on + storing client + explicit store=None: None is "unset", so the storing default applies (Mode B)."""
+    provider = _PscSpyHistoryProvider()
+    client = _PscSpyChatClient(provider=provider, stores_by_default=True, script=_psc_function_call_script())
+    agent = _psc_build_agent(
+        client, provider, require_per_service_call_history_persistence=True, default_options={"store": None}
+    )
+    session = agent.create_session()
+
+    with caplog.at_level(logging.WARNING, logger="agent_framework"):
+        await _psc_run(agent, "What's the weather in Seattle?", session, stream=stream)
+
+    assert client.saves_before_call == [0, 1]
+    assert provider.save_calls == 2
+    assert provider.get_calls == 0
+    assert session.service_session_id == _PSC_SERVICE_CONVERSATION_ID
+    assert any("load_messages" in record.message for record in caplog.records)
+    # store=None must not be forwarded to the client; the service decides its own default.
+    assert all("store" not in options for options in client.received_options)
+
+
+@_psc_stream_params
+async def test_psc_flag_on_respects_store_outputs_flag(stream: bool) -> None:
+    """Flag on: the provider's store_inputs/store_outputs flags still apply per service call."""
+    provider = _PscSpyHistoryProvider(store_inputs=True, store_outputs=False)
+    client = _PscSpyChatClient(provider=provider, stores_by_default=True, script=_psc_function_call_script())
+    agent = _psc_build_agent(client, provider, require_per_service_call_history_persistence=True)
+    session = agent.create_session()
+
+    await _psc_run(agent, "What's the weather in Seattle?", session, stream=stream)
+
+    assert provider.save_calls == 2
+    # Outputs disabled, so no assistant/tool-call messages were stored, only user/tool inputs.
+    assert provider.stored_messages
+    assert all(message.role != "assistant" for message in provider.stored_messages)
+
+
+# driver=False (control): persistence happens once, at the end of the run
+
+
+@_psc_stream_params
+async def test_psc_flag_off_store_false_persists_once_at_end(stream: bool) -> None:
+    """Flag off + non-storing client: nothing is persisted mid-run; one save at the end."""
+    provider = _PscSpyHistoryProvider()
+    client = _PscSpyChatClient(provider=provider, stores_by_default=False, script=_psc_function_call_script())
+    agent = _psc_build_agent(client, provider, require_per_service_call_history_persistence=False)
+    session = agent.create_session()
+
+    text = await _psc_run(agent, "What's the weather in Seattle?", session, stream=stream)
+
+    assert text == "It is sunny in Seattle."
+    assert client.call_count == 2
+    # The control contract: no save happened between the function call and the final completion.
+    assert client.saves_before_call == [0, 0]
+    assert provider.save_calls == 1
+
+
+@_psc_stream_params
+async def test_psc_flag_off_stores_by_default_persists_once_at_end(stream: bool) -> None:
+    """Flag off + storing client: once-per-run persistence, and the service conversation id propagates."""
+    provider = _PscSpyHistoryProvider()
+    client = _PscSpyChatClient(provider=provider, stores_by_default=True, script=_psc_function_call_script())
+    agent = _psc_build_agent(client, provider, require_per_service_call_history_persistence=False)
+    session = agent.create_session()
+
+    await _psc_run(agent, "What's the weather in Seattle?", session, stream=stream)
+
+    assert client.saves_before_call == [0, 0]
+    assert provider.save_calls == 1
+    assert session.service_session_id == _PSC_SERVICE_CONVERSATION_ID
+
+
+@_psc_stream_params
+async def test_psc_flag_on_storing_with_existing_conversation_id_does_not_raise(stream: bool) -> None:
+    """Allow side of the guard: flag on + storing client + an existing conversation_id resumes (no raise).
+
+    The non-storing path raises on an existing service-managed conversation id, but with a storing
+    client the run must proceed and the service conversation id must propagate to the session.
+    """
+    provider = _PscSpyHistoryProvider()
+    client = _PscSpyChatClient(provider=provider, stores_by_default=True, script=_psc_function_call_script())
+    agent = _psc_build_agent(client, provider, require_per_service_call_history_persistence=True)
+    session = agent.create_session()
+
+    if stream:
+        chunks: list[str] = []
+        async for update in agent.run(
+            "What's the weather in Seattle?",
+            session=session,
+            stream=True,
+            options={"conversation_id": "existing_conversation"},
+        ):
+            chunks.append(update.text or "")
+        text = "".join(chunks)
+    else:
+        result = await agent.run(
+            "What's the weather in Seattle?",
+            session=session,
+            options={"conversation_id": "existing_conversation"},
+        )
+        text = result.text
+
+    assert text == "It is sunny in Seattle."
+    # Persistence still happens per service call, and the real service id propagates to the session.
+    assert provider.save_calls == 2
+    assert provider.get_calls == 0
+    assert session.service_session_id == _PSC_SERVICE_CONVERSATION_ID
+
+
+@_psc_stream_params
+async def test_psc_flag_on_storing_two_runs_same_session(stream: bool) -> None:
+    """Storing mode across two runs on one session: persistence keeps happening, id is stable, no load.
+
+    The second run exercises the precedence branch where the session already carries a
+    service_session_id, which must continue to skip provider loading and keep persisting.
+    """
+    provider = _PscSpyHistoryProvider()
+    client = _PscSpyChatClient(provider=provider, stores_by_default=True, script=_psc_function_call_script())
+    agent = _psc_build_agent(client, provider, require_per_service_call_history_persistence=True)
+    session = agent.create_session()
+
+    await _psc_run(agent, "What's the weather in Seattle?", session, stream=stream)
+
+    assert provider.save_calls == 2
+    assert provider.get_calls == 0
+    first_run_service_id = session.service_session_id
+    assert first_run_service_id == _PSC_SERVICE_CONVERSATION_ID
+
+    # Reset the scripted client for a second run on the same session.
+    client._script = _psc_function_call_script()
+    client.call_count = 0
+    client.saves_before_call = []
+
+    await _psc_run(agent, "And in Portland?", session, stream=stream)
+
+    # Persistence keeps happening on the second run (two more saves), still per service call.
+    assert client.saves_before_call == [2, 3]
+    assert provider.save_calls == 4
+    # Loading stays skipped and the service conversation id stays stable across runs.
+    assert provider.get_calls == 0
+    assert session.service_session_id == first_run_service_id
+
+
+@_psc_stream_params
+async def test_psc_flag_on_storing_without_conversation_id_warns_every_call(
+    stream: bool, caplog: pytest.LogCaptureFixture
+) -> None:
+    """Storing mode but the client returns no conversation_id: warn on every service call.
+
+    Without an echoed conversation id the next run has nothing to resume from, so cross-turn
+    history can be lost silently. The warning fires per service call (no dedup) so the uncommon
+    failure mode cannot pass unnoticed.
+    """
+    provider = _PscSpyHistoryProvider()
+    client = _PscSpyChatClient(
+        provider=provider,
+        stores_by_default=True,
+        script=_psc_function_call_script(),
+        echo_conversation_id=False,
+    )
+    agent = _psc_build_agent(client, provider, require_per_service_call_history_persistence=True)
+    session = agent.create_session()
+
+    with caplog.at_level(logging.WARNING, logger="agent_framework"):
+        await _psc_run(agent, "What's the weather in Seattle?", session, stream=stream)
+
+    # Persistence still happens, but no service id is captured to resume from.
+    assert provider.save_calls == 2
+    assert session.service_session_id is None
+    # Two service calls -> the warning is emitted twice (one per call, not deduped).
+    missing_id_warnings = [r for r in caplog.records if "returned no conversation_id" in r.message]
+    assert len(missing_id_warnings) == 2

python/packages/core/tests/core/test_mcp.py

@@ -30,6 +30,7 @@ from agent_framework._mcp import (
     MCPTool,
     _build_prefixed_mcp_name,
     _get_input_model_from_mcp_prompt,
+    _normalize_additional_tool_argument_names,
     _normalize_mcp_name,
     _should_propagate_cancelled_error,
     logger,
@@ -6057,3 +6058,205 @@ async def test_max_wait_interrupts_long_poll_sleep(monkeypatch: pytest.MonkeyPat
 
 
 # endregion
+
+
+# region additional_tool_argument_names / allowlist filtering
+
+
+def test_normalize_additional_tool_argument_names_none() -> None:
+    global_extras, per_tool = _normalize_additional_tool_argument_names(None)
+    assert global_extras == set()
+    assert per_tool == {}
+
+
+def test_normalize_additional_tool_argument_names_sequence() -> None:
+    global_extras, per_tool = _normalize_additional_tool_argument_names(["a", "b", "a"])
+    assert global_extras == {"a", "b"}
+    assert per_tool == {}
+
+
+def test_normalize_additional_tool_argument_names_single_string() -> None:
+    # A bare string must be treated as a single name, not split into characters.
+    global_extras, per_tool = _normalize_additional_tool_argument_names("conversation_id")
+    assert global_extras == {"conversation_id"}
+    assert per_tool == {}
+
+
+def test_normalize_additional_tool_argument_names_mapping_with_global_key() -> None:
+    global_extras, per_tool = _normalize_additional_tool_argument_names({
+        "*": ["g1"],
+        "tool_a": ["a1", "a2"],
+        "tool_b": ["b1"],
+    })
+    assert global_extras == {"g1"}
+    assert per_tool == {"tool_a": {"a1", "a2"}, "tool_b": {"b1"}}
+
+
+def test_normalize_additional_tool_argument_names_mapping_with_string_values() -> None:
+    # A bare string mapping value is a single name, not an iterable of characters.
+    global_extras, per_tool = _normalize_additional_tool_argument_names({
+        "*": "conversation_id",
+        "tool_a": "custom",
+    })
+    assert global_extras == {"conversation_id"}
+    assert per_tool == {"tool_a": {"custom"}}
+
+
+def test_prepare_call_kwargs_strips_undeclared_arguments() -> None:
+    server = MCPTool(name="test_server")
+    server._tool_param_names_by_name = {"test_tool": {"param"}}
+
+    filtered, meta = server._prepare_call_kwargs(
+        "test_tool",
+        {"param": "value", "conversation_id": "c", "thread": object(), "unexpected": 1},
+    )
+
+    assert filtered == {"param": "value"}
+    assert meta is None
+
+
+def test_prepare_call_kwargs_global_extras_allowed() -> None:
+    server = MCPTool(name="test_server", additional_tool_argument_names=["conversation_id"])
+    server._tool_param_names_by_name = {"test_tool": {"param"}}
+
+    filtered, _ = server._prepare_call_kwargs(
+        "test_tool",
+        {"param": "value", "conversation_id": "c", "options": {}},
+    )
+
+    assert filtered == {"param": "value", "conversation_id": "c"}
+
+
+def test_prepare_call_kwargs_per_tool_and_global_extras() -> None:
+    server = MCPTool(
+        name="test_server",
+        additional_tool_argument_names={"*": ["conversation_id"], "test_tool": ["custom"]},
+    )
+    server._tool_param_names_by_name = {"test_tool": {"param"}, "other_tool": {"x"}}
+
+    filtered, _ = server._prepare_call_kwargs(
+        "test_tool",
+        {"param": "v", "conversation_id": "c", "custom": "y", "thread": object()},
+    )
+    assert filtered == {"param": "v", "conversation_id": "c", "custom": "y"}
+
+    # The per-tool extra does not leak to other tools; the global one still applies.
+    filtered_other, _ = server._prepare_call_kwargs(
+        "other_tool",
+        {"x": 1, "conversation_id": "c", "custom": "y"},
+    )
+    assert filtered_other == {"x": 1, "conversation_id": "c"}
+
+
+def test_prepare_call_kwargs_denylist_guards_server_declared_names() -> None:
+    # The denylist is a safety net for framework-named params a server *declares* in its
+    # schema: they are dropped so internal objects never leak. Names explicitly opted in
+    # via extras always win.
+    server = MCPTool(name="test_server", additional_tool_argument_names=["conversation_id"])
+    server._tool_param_names_by_name = {"test_tool": {"param", "thread"}}
+
+    filtered, _ = server._prepare_call_kwargs(
+        "test_tool",
+        {"param": "v", "thread": object(), "conversation_id": "c"},
+    )
+    # "thread" is declared by the schema but denylisted -> dropped; conversation_id opted in -> kept.
+    assert filtered == {"param": "v", "conversation_id": "c"}
+
+
+def test_prepare_call_kwargs_extras_override_denylist() -> None:
+    # Opting a denylisted framework name back in via extras takes precedence over the
+    # denylist safety net. "thread" is on the framework denylist, but an explicit extra wins.
+    server = MCPTool(name="test_server", additional_tool_argument_names=["thread"])
+    server._tool_param_names_by_name = {"test_tool": {"param"}}
+
+    sentinel = object()
+    filtered, _ = server._prepare_call_kwargs(
+        "test_tool",
+        {"param": "v", "thread": sentinel, "conversation_id": "c"},
+    )
+    # "thread" opted in via extras -> kept despite the denylist; conversation_id is denylisted,
+    # not declared, and not opted in -> dropped.
+    assert filtered == {"param": "v", "thread": sentinel}
+
+
+def test_prepare_call_kwargs_zero_arg_tool_passes_no_arguments() -> None:
+    server = MCPTool(name="test_server")
+    server._tool_param_names_by_name = {"test_tool": set()}
+
+    filtered, _ = server._prepare_call_kwargs(
+        "test_tool",
+        {"conversation_id": "c", "thread": object(), "stray": 1},
+    )
+    assert filtered == {}
+
+
+def test_prepare_call_kwargs_unknown_tool_passes_only_global_extras() -> None:
+    server = MCPTool(name="test_server", additional_tool_argument_names=["conversation_id"])
+    # No entry in _tool_param_names_by_name for this tool name.
+
+    filtered, _ = server._prepare_call_kwargs(
+        "unknown_tool",
+        {"conversation_id": "c", "other": 1},
+    )
+    assert filtered == {"conversation_id": "c"}
+
+
+def test_prepare_call_kwargs_extracts_meta() -> None:
+    server = MCPTool(name="test_server")
+    server._tool_param_names_by_name = {"test_tool": {"param"}}
+
+    filtered, meta = server._prepare_call_kwargs(
+        "test_tool",
+        {"param": "v", "_meta": {"trace": "abc"}},
+    )
+    assert filtered == {"param": "v"}
+    assert meta is not None
+    assert meta.get("trace") == "abc"
+
+
+async def test_call_tool_forwards_only_declared_arguments() -> None:
+    """End-to-end: framework runtime kwargs are stripped before reaching the server."""
+
+    class TestServer(MCPTool):
+        async def connect(self):
+            self.session = Mock(spec=ClientSession)
+            self.session.list_tools = AsyncMock(
+                return_value=types.ListToolsResult(
+                    tools=[
+                        types.Tool(
+                            name="test_tool",
+                            description="Test tool",
+                            inputSchema={
+                                "type": "object",
+                                "properties": {"param": {"type": "string"}},
+                                "required": ["param"],
+                            },
+                        )
+                    ]
+                )
+            )
+            self.session.call_tool = AsyncMock(
+                return_value=types.CallToolResult(content=[types.TextContent(type="text", text="ok")])
+            )
+
+        def get_mcp_client(self) -> _AsyncGeneratorContextManager[Any, None]:
+            return None
+
+    server = TestServer(name="test_server", additional_tool_argument_names=["conversation_id"])
+    async with server:
+        await server.load_tools()
+        session_mock = server.session
+        await server.call_tool(
+            "test_tool",
+            param="value",
+            conversation_id="c",
+            thread=object(),
+            response_format=object(),
+        )
+
+        session_mock.call_tool.assert_called_once()
+        _, call_kwargs = session_mock.call_tool.call_args
+        assert call_kwargs["arguments"] == {"param": "value", "conversation_id": "c"}
+
+
+# endregion

python/packages/foundry/pyproject.toml

@@ -4,7 +4,7 @@ description = "Microsoft Foundry integrations for Microsoft Agent Framework."
 authors = [{ name = "Microsoft", email = "af-support@microsoft.com"}]
 readme = "README.md"
 requires-python = ">=3.10"
-version = "1.8.0"
+version = "1.8.1"
 license-files = ["LICENSE"]
 urls.homepage = "https://aka.ms/agent-framework"
 urls.source = "https://github.com/microsoft/agent-framework/tree/main/python"
@@ -23,8 +23,8 @@ classifiers = [
   "Typing :: Typed",
 ]
 dependencies = [
-    "agent-framework-core>=1.8.0,<2",
-    "agent-framework-openai>=1.8.0,<2",
+    "agent-framework-core>=1.8.1,<2",
+    "agent-framework-openai>=1.8.1,<2",
     "azure-ai-inference>=1.0.0b9,<1.0.0b10",
     "azure-ai-projects>=2.2.0,<3.0",
 ]

python/packages/foundry_hosting/pyproject.toml

@@ -4,7 +4,7 @@ description = "Foundry Hosting integration for Microsoft Agent Framework."
 authors = [{ name = "Microsoft", email = "af-support@microsoft.com"}]
 readme = "README.md"
 requires-python = ">=3.10"
-version = "1.0.0a260604"
+version = "1.0.0a260609"
 license-files = ["LICENSE"]
 urls.homepage = "https://aka.ms/agent-framework"
 urls.source = "https://github.com/microsoft/agent-framework/tree/main/python"
@@ -23,7 +23,7 @@ classifiers = [
   "Typing :: Typed",
 ]
 dependencies = [
-    "agent-framework-core>=1.8.0,<2",
+    "agent-framework-core>=1.8.1,<2",
     "azure-ai-agentserver-core>=2.0.0b3,<3",
     "azure-ai-agentserver-responses>=1.0.0b7,<2",
     "azure-ai-agentserver-invocations>=1.0.0b3,<2",

python/packages/gemini/pyproject.toml

@@ -4,7 +4,7 @@ description = "Google Gemini integration for Microsoft Agent Framework."
 authors = [{ name = "Microsoft", email = "af-support@microsoft.com"}]
 readme = "README.md"
 requires-python = ">=3.10"
-version = "1.0.0a260521"
+version = "1.0.0a260609"
 license-files = ["LICENSE"]
 urls.homepage = "https://aka.ms/agent-framework"
 urls.source = "https://github.com/microsoft/agent-framework/tree/main/python"
@@ -24,7 +24,7 @@ classifiers = [
   "Typing :: Typed",
 ]
 dependencies = [
-    "agent-framework-core>=1.6.0,<2.0",
+    "agent-framework-core>=1.8.1,<2.0",
     "google-genai>=1.65.0,<2.0.0",
 ]
 

python/packages/mem0/pyproject.toml

@@ -4,7 +4,7 @@ description = "Mem0 integration for Microsoft Agent Framework."
 authors = [{ name = "Microsoft", email = "af-support@microsoft.com"}]
 readme = "README.md"
 requires-python = ">=3.10"
-version = "1.0.0b260521"
+version = "1.0.0b260609"
 license-files = ["LICENSE"]
 urls.homepage = "https://aka.ms/agent-framework"
 urls.source = "https://github.com/microsoft/agent-framework/tree/main/python"
@@ -23,7 +23,7 @@ classifiers = [
   "Typing :: Typed",
 ]
 dependencies = [
-    "agent-framework-core>=1.6.0,<2",
+    "agent-framework-core>=1.8.1,<2",
     "mem0ai>=1.0.0,<2",
 ]
 

python/packages/openai/agent_framework_openai/_chat_client.py

@@ -1997,7 +1997,11 @@ class RawOpenAIChatClient(  # type: ignore[misc]
         metadata: dict[str, Any] = response.metadata or {}
         contents: list[Content] = []
         local_shell_tool_name = self._get_local_shell_tool_name(options.get("tools"))
-        for item in response.output:  # type: ignore[reportUnknownMemberType]
+        try:
+            response_outputs = response.output  # type: ignore[reportUnknownMemberType]
+        except AttributeError:
+            response_outputs = []
+        for item in response_outputs:  # type: ignore[reportUnknownVariableType]
             match item.type:
                 # types:
                 # ParsedResponseOutputMessage[Unknown] |

python/packages/openai/agent_framework_openai/_chat_completion_client.py

@@ -788,13 +788,13 @@ class RawOpenAIChatCompletionClient(  # type: ignore[misc]
     def _get_metadata_from_chat_response(self, response: ChatCompletion) -> dict[str, Any]:
         """Get metadata from a chat response."""
         return {
-            "system_fingerprint": response.system_fingerprint,
+            "system_fingerprint": getattr(response, "system_fingerprint", None),
         }
 
     def _get_metadata_from_streaming_chat_response(self, response: ChatCompletionChunk) -> dict[str, Any]:
         """Get metadata from a streaming chat response."""
         return {
-            "system_fingerprint": response.system_fingerprint,
+            "system_fingerprint": getattr(response, "system_fingerprint", None),
         }
 
     def _get_metadata_from_chat_choice(self, choice: Choice | ChunkChoice) -> dict[str, Any]:

python/packages/openai/pyproject.toml

@@ -4,7 +4,7 @@ description = "OpenAI integrations for Microsoft Agent Framework."
 authors = [{ name = "Microsoft", email = "af-support@microsoft.com"}]
 readme = "README.md"
 requires-python = ">=3.10"
-version = "1.8.0"
+version = "1.8.1"
 license-files = ["LICENSE"]
 urls.homepage = "https://aka.ms/agent-framework"
 urls.source = "https://github.com/microsoft/agent-framework/tree/main/python"
@@ -23,7 +23,7 @@ classifiers = [
   "Typing :: Typed",
 ]
 dependencies = [
-    "agent-framework-core>=1.8.0,<2",
+    "agent-framework-core>=1.8.1,<2",
     "openai>=1.99.0,<3",
 ]
 

python/pyproject.toml

@@ -4,7 +4,7 @@ description = "Microsoft Agent Framework for building AI Agents with Python. Thi
 authors = [{ name = "Microsoft", email = "af-support@microsoft.com"}]
 readme = "README.md"
 requires-python = ">=3.10"
-version = "1.8.0"
+version = "1.8.1"
 license-files = ["LICENSE"]
 urls.homepage = "https://aka.ms/agent-framework"
 urls.source = "https://github.com/microsoft/agent-framework/tree/main/python"
@@ -23,7 +23,7 @@ classifiers = [
   "Typing :: Typed",
 ]
 dependencies = [
-    "agent-framework-core[all]==1.8.0",
+    "agent-framework-core[all]==1.8.1",
 ]
 
 [dependency-groups]

python/pyrightconfig.samples.json

@@ -7,6 +7,7 @@
         "**/demos/**",
         "**/_to_delete/**",
         "**/05-end-to-end/**",
+        "**/harness/**",
         "**/agent_with_foundry_tracing.py",
         "**/azure_responses_client_with_foundry.py"
     ],

python/pyrightconfig.samples.py310.json

@@ -7,6 +7,7 @@
         "**/demos/**",
         "**/_to_delete/**",
         "**/05-end-to-end/**",
+        "**/harness/**",
         "**/agent_with_foundry_tracing.py",
         "**/azure_responses_client_with_foundry.py",
         "**/github_copilot/**"

python/samples/02-agents/harness/console/README.md

@@ -0,0 +1,94 @@
+# Harness Console
+
+A Textual-based terminal UI for running and observing AI agents built with the Agent Framework.
+
+## Quick Start
+
+```python
+from console import run_agent_async, build_default_observers
+
+await run_agent_async(
+    agent=my_agent,
+    session=my_session,
+    observers=build_default_observers(),
+)
+```
+
+See [`harness_research.py`](../harness_research.py) for a complete example.
+
+## Package Structure
+
+```
+console/
+├── __init__.py              # Public API exports
+├── harness_console.py       # run_agent_async() entry point
+├── app.py                   # HarnessApp (Textual application)
+├── app_state.py             # HarnessAppState, enums, data types
+├── agent_runner.py          # HarnessAgentRunner (streaming orchestration)
+├── state_driver.py          # IUXStateDriver protocol
+├── textual_state_driver.py  # Textual implementation of IUXStateDriver
+├── formatters.py            # Tool call formatters
+├── observers/               # Lifecycle observers
+│   ├── base.py              #   ConsoleObserver abstract base
+│   ├── text_output.py       #   Streaming text display
+│   ├── tool_call_display.py #   Tool call formatting
+│   ├── tool_approval.py     #   User approval for tool calls
+│   ├── error_display.py     #   Error messages
+│   ├── usage_display.py     #   Token usage tracking
+│   └── reasoning_display.py #   Reasoning/thinking blocks
+├── components/              # Textual UI widgets
+│   ├── scroll_panel.py      #   Conversation history
+│   ├── text_input.py        #   User text input
+│   ├── list_selection.py    #   Multiple choice selector
+│   ├── agent_status.py      #   Spinner + usage display
+│   └── agent_mode_help.py   #   Mode indicator + help text
+└── commands/                # Slash command handlers
+    ├── base.py              #   CommandHandler abstract base
+    ├── exit_handler.py      #   /exit
+    ├── mode_handler.py      #   /mode [plan|execute]
+    ├── todo_handler.py      #   /todos
+    └── session_handler.py   #   /session-export, /session-import
+```
+
+## Public API
+
+| Export | Description |
+|--------|-------------|
+| `run_agent_async` | Main entry point — runs the Textual app with an agent |
+| `build_default_observers` | Factory for the standard observer set |
+| `build_default_command_handlers` | Factory for slash command handlers |
+| `ConsoleObserver` | Base class for custom observers |
+| `ToolCallFormatter` | Base class for custom tool formatters |
+| `CommandHandler` | Base class for custom slash commands |
+
+## Architecture
+
+The console follows a unidirectional data flow:
+
+```
+AgentRunner → Observers → StateDriver → AppState → Textual UI
+                                ↑
+                          User Input (app.py)
+```
+
+- **AgentRunner** streams responses from the agent and dispatches events to observers.
+- **Observers** process events (text chunks, tool calls, errors) and update the state driver.
+- **StateDriver** (`IUXStateDriver`) mutates `HarnessAppState` and notifies the UI.
+- **Textual App** reads state and syncs widgets on each notification.
+
+### Key Design Choices
+
+| Concern | Approach |
+|---------|----------|
+| Rendering | Textual widgets + Rich markup (no manual ANSI) |
+| State | Single `HarnessAppState` dataclass, mutated by driver |
+| Streaming text | Truncate-and-rewrite on RichLog for flicker-free updates |
+| Extensibility | Custom observers, formatters, and commands via base classes |
+| Follow-up questions | Observer returns `FollowUpQuestion` → UI shows prompt/choices |
+
+## Dependencies
+
+- `textual` — TUI framework
+- `rich` — Text formatting
+- `agent-framework` — Core agent framework
+

python/samples/02-agents/harness/console/__init__.py

@@ -0,0 +1,27 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""Harness Console - A Textual-based TUI for AI agent interactions.
+
+This package provides a rich terminal interface for running and observing
+AI agents, with streaming output, tool call display, follow-up questions,
+and token usage tracking.
+"""
+
+from .commands import CommandHandler, build_default_command_handlers
+from .formatters import ToolCallFormatter
+from .harness_console import run_agent_async
+from .observers import (
+    ConsoleObserver,
+    build_default_observers,
+    build_observers_with_planning,
+)
+
+__all__ = [
+    "CommandHandler",
+    "ConsoleObserver",
+    "ToolCallFormatter",
+    "build_default_command_handlers",
+    "build_default_observers",
+    "build_observers_with_planning",
+    "run_agent_async",
+]

python/samples/02-agents/harness/console/agent_runner.py

@@ -0,0 +1,343 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""Agent runner orchestration for the harness console.
+
+This module provides the HarnessAgentRunner class, which orchestrates agent
+invocations with observer lifecycle management. It handles:
+- User input dispatch
+- Agent streaming with observer notifications
+- Follow-up action collection
+- Streaming state management
+"""
+
+from __future__ import annotations
+
+import asyncio
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from agent_framework import Agent, AgentSession
+
+    from .app_state import FollowUpAction
+    from .observers.base import ConsoleObserver
+    from .state_driver import IUXStateDriver
+
+
+class HarnessAgentRunner:
+    """Orchestrates agent invocations driven by user-input events from the UI.
+
+    The component invokes the runner's input handlers (run_turn) directly;
+    the runner mutates UI state through the supplied IUXStateDriver.
+
+    This is a minimal implementation focusing on the core agent loop without
+    command handling or complex message injection (those can be added later).
+    """
+
+    def __init__(
+        self,
+        agent: Agent,
+        observers: list[ConsoleObserver],
+        state_driver: IUXStateDriver,
+        *,
+        max_context_window_tokens: int | None = None,
+        max_output_tokens: int | None = None,
+    ) -> None:
+        """Initialize the agent runner.
+
+        Args:
+            agent: The agent to orchestrate.
+            observers: List of console observers for lifecycle events.
+            state_driver: The UI state driver for observer updates.
+            max_context_window_tokens: Optional max context window size for usage display.
+            max_output_tokens: Optional max output tokens for usage display.
+        """
+        self._agent = agent
+        self._observers = observers
+        self._ux = state_driver
+        self._max_context_window_tokens = max_context_window_tokens
+        self._max_output_tokens = max_output_tokens
+        self._input_gate = asyncio.Semaphore(1)  # Single turn at a time
+
+    async def run_turn(
+        self,
+        user_input: str,
+        session: AgentSession | None = None,
+    ) -> None:
+        """Run a single agent turn with the given user input.
+
+        Echoes the input, then delegates to the agent loop.
+
+        Args:
+            user_input: The user's input text.
+            session: Optional agent session for conversation history.
+        """
+        async with self._input_gate:
+            self._ux.write_user_input_echo(user_input)
+
+            from agent_framework import Message
+
+            messages = [Message(role="user", contents=[user_input])]
+            await self._run_agent_loop(messages, session)
+
+    async def start_agent_turn(
+        self,
+        messages: list,
+        session: AgentSession | None = None,
+    ) -> None:
+        """Resume the agent loop with pre-built messages (from follow-up responses).
+
+        Called by the app after the user finishes answering follow-up questions.
+        If messages is empty, just completes the turn.
+
+        Args:
+            messages: List of Message objects to send to the agent.
+            session: Optional agent session.
+        """
+        async with self._input_gate:
+            if not messages:
+                self._complete_turn()
+                return
+            await self._run_agent_loop(messages, session)
+
+    async def _run_agent_loop(
+        self,
+        messages: list,
+        session: AgentSession | None,
+    ) -> None:
+        """Run the agent loop, re-invoking as needed for follow-up messages.
+
+        Loops while there are messages to send. After each stream:
+        - Collects follow-up actions from observers
+        - If questions exist → queue them and return (UI will collect answers)
+        - If only direct messages → loop with those messages
+        - If nothing → complete the turn
+
+        Args:
+            messages: Initial messages to send.
+            session: Optional agent session.
+        """
+        next_messages = messages
+
+        while next_messages:
+            # Configure run options
+            options = self._configure_run_options(session)
+
+            # Begin streaming
+            self._ux.begin_streaming()
+            self._ux.begin_streaming_output()
+            self._ux.set_show_spinner(True)
+
+            try:
+                await self._stream_response_messages(next_messages, session, options)
+            except Exception as ex:
+                self._ux.append_info_line(
+                    f"❌ Stream error: {ex.__class__.__name__}:\n{ex}",
+                    color="red",
+                )
+
+            # Stop spinner and end streaming output
+            self._ux.set_show_spinner(False)
+
+            # Collect follow-up actions from observers
+            follow_up_actions = await self._collect_follow_up_actions(session)
+
+            # Separate direct messages from questions
+            has_follow_ups = len(follow_up_actions) > 0
+
+            # Write no-text warning if applicable
+            await self._ux.write_no_text_warning(has_follow_ups)
+
+            # Enqueue all follow-up actions
+            for action in follow_up_actions:
+                self._ux.enqueue_follow_up_action(action)
+
+            # Check if there are pending questions (UI needs user input)
+            if self._ux.has_pending_questions():
+                # Pause — the UI will collect answers and call start_agent_turn
+                return
+
+            # No questions — drain any accumulated direct messages and loop
+            drained = self._ux.take_follow_up_responses()
+            next_messages = drained if drained else None
+
+        self._complete_turn()
+
+    def _complete_turn(self) -> None:
+        """Complete the current turn (end streaming)."""
+        self._ux.end_streaming()
+
+    def _configure_run_options(
+        self,
+        session: AgentSession | None,
+    ) -> dict:
+        """Configure run options via observers.
+
+        Each observer can modify the options dict to influence agent behavior.
+
+        Args:
+            session: Optional agent session.
+
+        Returns:
+            Options dict for agent.run().
+        """
+        options = {}
+        for observer in self._observers:
+            observer.configure_run_options(options, self._agent, session)
+        return options
+
+    async def _stream_response(
+        self,
+        user_input: str,
+        session: AgentSession | None,
+        options: dict,
+    ) -> None:
+        """Stream agent response from a text input and dispatch to observers.
+
+        Args:
+            user_input: The user's input text.
+            session: Optional agent session.
+            options: Run options configured by observers.
+        """
+        # Stream response using agent.run(stream=True)
+        stream = self._agent.run(
+            user_input,
+            stream=True,
+            session=session,
+            options=options,
+        )
+
+        # Process each update chunk
+        async for update in stream:
+            await self._dispatch_update(update, session)
+
+        # Extract usage from the final response
+        self._extract_usage(stream)
+
+    async def _stream_response_messages(
+        self,
+        messages: list,
+        session: AgentSession | None,
+        options: dict,
+    ) -> None:
+        """Stream agent response from Message objects and dispatch to observers.
+
+        Args:
+            messages: List of Message objects to send.
+            session: Optional agent session.
+            options: Run options configured by observers.
+        """
+        stream = self._agent.run(
+            messages,
+            stream=True,
+            session=session,
+            options=options,
+        )
+
+        async for update in stream:
+            await self._dispatch_update(update, session)
+
+        self._extract_usage(stream)
+
+    def _extract_usage(self, stream) -> None:
+        """Extract token usage from a completed stream."""
+        try:
+            get_final = getattr(stream, "get_final_response", None)
+            if not get_final:
+                return
+
+            import inspect
+
+            if inspect.iscoroutinefunction(get_final):
+                return
+
+            final_response = get_final()
+            if final_response is None:
+                return
+
+            usage = getattr(final_response, "usage_details", None)
+            if not isinstance(usage, dict):
+                return
+
+            input_tokens = usage.get("input_token_count", 0) or 0
+            output_tokens = usage.get("output_token_count", 0) or 0
+            if input_tokens or output_tokens:
+                self._ux.set_usage_text(self._format_usage(input_tokens, output_tokens))
+        except (AttributeError, TypeError):
+            pass
+
+    async def _dispatch_update(
+        self,
+        update,  # AgentResponseUpdate
+        session: AgentSession | None,
+    ) -> None:
+        """Dispatch a single update to all observers.
+
+        Calls observer lifecycle methods in order:
+        1. on_response_update (once per update)
+        2. on_content (for each content item)
+        3. on_text (if text is present)
+
+        Args:
+            update: The agent response update.
+            session: Optional agent session.
+        """
+        # on_response_update
+        for observer in self._observers:
+            await observer.on_response_update(self._ux, update, self._agent, session)
+
+        # on_content for each content item
+        if hasattr(update, "contents") and update.contents:
+            for content in update.contents:
+                for observer in self._observers:
+                    await observer.on_content(self._ux, content, self._agent, session)
+
+        # on_text for text chunks
+        if hasattr(update, "text") and update.text:
+            for observer in self._observers:
+                await observer.on_text(self._ux, update.text, self._agent, session)
+
+    async def _collect_follow_up_actions(
+        self,
+        session: AgentSession | None,
+    ) -> list[FollowUpAction]:
+        """Collect follow-up actions from all observers.
+
+        Called after streaming completes to gather any follow-up questions
+        or messages from observers.
+
+        Args:
+            session: Optional agent session.
+
+        Returns:
+            List of follow-up actions from all observers.
+        """
+        actions: list[FollowUpAction] = []
+        for observer in self._observers:
+            observer_actions = await observer.on_stream_complete(
+                self._ux, self._agent, session
+            )
+            if observer_actions:
+                actions.extend(observer_actions)
+        return actions
+
+    def _format_usage(self, input_tokens: int, output_tokens: int) -> str:
+        """Format token counts matching C# harness style: 📊 Tokens — input: X | output: Y | total: Z."""
+        total_tokens = input_tokens + output_tokens
+
+        input_budget = None
+        if self._max_context_window_tokens and self._max_output_tokens:
+            input_budget = self._max_context_window_tokens - self._max_output_tokens
+
+        return (
+            f"📊 Tokens — input: {self._format_token_count(input_tokens, input_budget)}"
+            f" | output: {self._format_token_count(output_tokens, self._max_output_tokens)}"
+            f" | total: {self._format_token_count(total_tokens, self._max_context_window_tokens)}"
+        )
+
+    @staticmethod
+    def _format_token_count(count: int, budget: int | None) -> str:
+        """Format a token count, optionally showing budget percentage."""
+        if budget and budget > 0:
+            pct = count / budget * 100
+            return f"{count:,}/{budget:,} ({pct:.1f}%)"
+        return f"{count:,}"

python/samples/02-agents/harness/console/app.py

@@ -0,0 +1,541 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""Main Textual application for the harness console.
+
+This module provides the HarnessApp - the main Textual application that
+composes all UI components and integrates with the agent runner.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from textual import on, work
+from textual.app import App, ComposeResult
+from textual.binding import Binding
+from textual.containers import Container, Vertical
+from textual.css.query import NoMatches
+from textual.widgets import Input, Static
+
+from .app_state import (
+    BottomPanelMode,
+    HarnessAppState,
+    OutputEntryType,
+)
+from .components import (
+    AgentModeAndHelp,
+    AgentStatus,
+    HarnessListSelection,
+    HarnessScrollPanel,
+    HarnessTextInput,
+    PromptRule,
+)
+from .textual_state_driver import HarnessConsoleUXStateDriver
+
+if TYPE_CHECKING:
+    from agent_framework import Agent, AgentSession
+
+    from .agent_runner import HarnessAgentRunner
+    from .commands import CommandHandler
+    from .observers.base import ConsoleObserver
+
+
+class HarnessApp(App[None]):
+    """Main Textual application for the harness console.
+
+    Composes the scroll panel (conversation history), status bar (spinner, usage),
+    mode/help display, and bottom panel (text input, list selection, or streaming
+    indicator). Routes user input to the agent runner.
+    """
+
+    CSS = """
+    Screen {
+        background: $background;
+    }
+
+    #scroll-panel {
+        height: 1fr;
+        padding: 0 1;
+        background: transparent;
+    }
+
+    #bottom-panel {
+        height: auto;
+    }
+
+    #text-input-container {
+        height: 1;
+        display: block;
+    }
+
+    #list-selection-container {
+        height: auto;
+        max-height: 12;
+        display: none;
+    }
+
+    #streaming-indicator {
+        height: 1;
+        display: none;
+    }
+
+    #status-bar {
+        height: 1;
+    }
+
+    #mode-help {
+        height: 1;
+    }
+
+    #top-rule {
+        height: 1;
+    }
+
+    #bottom-rule {
+        height: 1;
+    }
+
+    #separator-rule {
+        height: 1;
+    }
+
+    #text-input {
+        height: 1;
+    }
+
+    .hidden {
+        display: none;
+    }
+
+    .visible {
+        display: block;
+    }
+
+    .input-field {
+        border: none;
+        padding: 0;
+        min-height: 1;
+        height: 1;
+        background: transparent;
+    }
+
+    .input-field:focus {
+        border: none;
+        background: transparent;
+    }
+
+    .prompt-container {
+        height: 1;
+    }
+
+    .prompt-label {
+        width: 2;
+        min-width: 2;
+        height: 1;
+    }
+    """
+
+    BINDINGS = [
+        Binding("ctrl+c", "quit", "Quit", show=False),
+        Binding("ctrl+q", "quit", "Quit", show=False),
+    ]
+
+    def __init__(
+        self,
+        agent: Agent,
+        observers: list[ConsoleObserver],
+        session: AgentSession | None = None,
+        mode_colors: dict[str, str] | None = None,
+        initial_mode: str | None = None,
+        placeholder: str = "Type a message and press Enter...",
+        title: str = "Harness Console",
+        max_context_window_tokens: int | None = None,
+        max_output_tokens: int | None = None,
+        command_handlers: list[CommandHandler] | None = None,
+    ) -> None:
+        """Initialize the harness console application.
+
+        Args:
+            agent: The agent to run.
+            observers: List of console observers.
+            session: Optional agent session.
+            mode_colors: Optional mode color mapping.
+            initial_mode: Initial agent mode.
+            placeholder: Input placeholder text.
+            title: Application title.
+            max_context_window_tokens: Optional max context window tokens for usage display.
+            max_output_tokens: Optional max output tokens for usage display.
+            command_handlers: Optional list of command handlers. If None, auto-detected.
+        """
+        super().__init__()
+        self.title = title
+        self._agent = agent
+        self._observers = observers
+        self._session = session
+        self._mode_colors = mode_colors
+        self._initial_mode = initial_mode
+        self._placeholder = placeholder
+        self._max_context_window_tokens = max_context_window_tokens
+        self._max_output_tokens = max_output_tokens
+
+        # Build command handlers
+        if command_handlers is None:
+            from .commands import build_default_command_handlers
+
+            self._command_handlers = build_default_command_handlers(
+                agent, mode_colors=mode_colors
+            )
+        else:
+            self._command_handlers = command_handlers
+
+        # Compute help text from command handlers
+        help_parts = [
+            h.get_help_text()
+            for h in self._command_handlers
+            if h.get_help_text() is not None
+        ]
+        help_text = ", ".join(help_parts) if help_parts else None
+
+        # State and driver
+        self._app_state = HarnessAppState(
+            placeholder=placeholder,
+            mode_text=initial_mode,
+            help_text=help_text,
+        )
+        self._ux_driver = HarnessConsoleUXStateDriver(
+            app_state=self._app_state,
+            on_state_changed=self._on_state_changed,
+            mode_colors=mode_colors,
+        )
+
+        # Agent runner (created after init)
+        self._runner: HarnessAgentRunner | None = None
+
+    @property
+    def ux_driver(self) -> HarnessConsoleUXStateDriver:
+        """Get the UX state driver."""
+        return self._ux_driver
+
+    @property
+    def runner(self) -> HarnessAgentRunner | None:
+        """Get the agent runner."""
+        return self._runner
+
+    def compose(self) -> ComposeResult:
+        """Compose the application layout."""
+        with Vertical():
+            # Main scroll panel for conversation history
+            yield HarnessScrollPanel(id="scroll-panel")
+
+            # Blank line separating scroll content from status area
+            yield Static(" ", id="separator-rule")
+
+            # Status bar (spinner + usage)
+            yield AgentStatus(id="status-bar")
+
+            # Top rule (mode-colored)
+            yield PromptRule(id="top-rule")
+
+            # Bottom panel - switches between text input, list selection, streaming
+            with Container(id="bottom-panel"):
+                # Text input (default)
+                with Container(id="text-input-container"):
+                    text_input = HarnessTextInput(id="text-input")
+                    text_input.placeholder = self._placeholder
+                    yield text_input
+
+                # List selection (for follow-up questions)
+                with Container(id="list-selection-container"):
+                    yield HarnessListSelection(id="list-selection")
+
+            # Bottom rule (mode-colored)
+            yield PromptRule(id="bottom-rule")
+
+            # Mode and help
+            yield AgentModeAndHelp(id="mode-help")
+
+    def on_mount(self) -> None:
+        """Initialize after mount."""
+        # Create agent runner now that everything is set up
+        from .agent_runner import HarnessAgentRunner
+
+        self._runner = HarnessAgentRunner(
+            agent=self._agent,
+            observers=self._observers,
+            state_driver=self._ux_driver,
+            max_context_window_tokens=self._max_context_window_tokens,
+            max_output_tokens=self._max_output_tokens,
+        )
+
+        # Set initial mode
+        if self._initial_mode:
+            self._ux_driver.current_mode = self._initial_mode
+
+        # Focus the text input
+        try:
+            text_input = self.query_one("#text-input", HarnessTextInput)
+            text_input.focus_input()
+        except NoMatches:
+            pass
+
+        # Set initial rule colors and mode display
+        self._sync_mode_help()
+
+    # --- Event handlers ---
+
+    @on(HarnessTextInput.Submitted)
+    def on_text_submitted(self, event: HarnessTextInput.Submitted) -> None:
+        """Handle text input submission."""
+        text = event.value.strip()
+        if not text:
+            return
+
+        if self._app_state.pending_questions:
+            # Answer the current follow-up question
+            self._handle_follow_up_answer(text)
+        elif self._app_state.mode == BottomPanelMode.STREAMING:
+            # Input during streaming (message injection placeholder)
+            pass
+        elif text.startswith("/"):
+            # Try command handlers
+            self._try_command_handlers(text)
+        else:
+            # Normal user input - run agent turn
+            self._run_agent_turn(text)
+
+    @work(exclusive=True, thread=False)
+    async def _try_command_handlers(self, text: str) -> None:
+        """Try each command handler; fall through to agent if none match."""
+        session = self._session
+        if session is None:
+            # No session — fall through to agent turn
+            self._run_agent_turn(text)
+            return
+
+        for handler in self._command_handlers:
+            if await handler.try_handle(text, session, self._ux_driver):
+                # Command handled — check for shutdown/session swap signals
+                self._process_command_signals()
+                return
+
+        # No handler matched — treat as normal agent input
+        self._run_agent_turn(text)
+
+    def _process_command_signals(self) -> None:
+        """Check and process signals set by command handlers."""
+        if self._app_state.shutdown_requested:
+            self.exit()
+            return
+
+        if self._app_state.replaced_session is not None:
+            self._session = self._app_state.replaced_session  # type: ignore[assignment]
+            self._app_state.replaced_session = None
+            self._ux_driver.append_info_line("Session replaced.")
+
+        self._sync_ui_from_state()
+
+    @on(HarnessListSelection.Selected)
+    def on_list_selected(self, event: HarnessListSelection.Selected) -> None:
+        """Handle list selection."""
+        self._handle_follow_up_answer(event.value)
+
+    # --- Agent turn ---
+
+    @work(exclusive=True, thread=False)
+    async def _run_agent_turn(self, text: str) -> None:
+        """Run an agent turn in a background worker."""
+        if self._runner is None:
+            return
+
+        await self._runner.run_turn(text, session=self._session)
+
+        # After turn completes, check for follow-up questions
+        self._sync_ui_from_state()
+
+    # --- Follow-up question handling ---
+
+    @work(exclusive=True, thread=False)
+    async def _handle_follow_up_answer(self, answer: str) -> None:
+        """Handle a user's answer to a follow-up question."""
+        if not self._app_state.pending_questions:
+            return
+
+        question = self._app_state.pending_questions[0]
+
+        # Call the continuation
+        result_message = await question.continuation(answer, self._ux_driver)
+
+        # Add result to accumulated responses
+        if result_message is not None:
+            self._ux_driver.add_follow_up_response(result_message)
+
+        # Advance to next question
+        self._ux_driver.advance_follow_up_question()
+
+        # If no more questions, resume the agent with accumulated responses
+        if not self._app_state.pending_questions:
+            responses = self._ux_driver.take_follow_up_responses()
+            if responses and self._runner:
+                await self._runner.start_agent_turn(responses, session=self._session)
+
+        self._sync_ui_from_state()
+
+    # --- State synchronization ---
+
+    def _on_state_changed(self) -> None:
+        """Called by state driver when state changes - schedule UI sync.
+
+        Since the agent runner uses @work(thread=False), state changes happen
+        on the main event loop. We use call_later to batch updates.
+        """
+        self.call_later(self._sync_ui_from_state)
+
+    def _sync_ui_from_state(self) -> None:
+        """Synchronize UI components with current application state."""
+        state = self._app_state
+
+        # Update scroll panel with new entries
+        self._sync_scroll_panel()
+
+        # Update bottom panel mode
+        self._sync_bottom_panel(state.mode)
+
+        # Hide status bar and mode/help during list selection (matching C#)
+        is_list_mode = state.mode == BottomPanelMode.LIST_SELECTION
+        self._sync_chrome_visibility(not is_list_mode)
+
+        # Update status bar
+        self._sync_status_bar()
+
+        # Update mode/help display
+        self._sync_mode_help()
+
+    def _sync_scroll_panel(self) -> None:
+        """Sync the scroll panel with output entries."""
+        try:
+            panel = self.query_one("#scroll-panel", HarnessScrollPanel)
+        except NoMatches:
+            return
+
+        entries = self._app_state.output_entries
+        rendered_count = getattr(self, "_rendered_entry_count", 0)
+
+        if rendered_count < len(entries):
+            # There are new entries to render
+            for entry in entries[rendered_count:]:
+                if entry.type == OutputEntryType.STREAMING_TEXT:
+                    panel.set_streaming_entry(entry)
+                else:
+                    # End any active streaming before appending other entry types
+                    panel.end_streaming()
+                    panel.append_entry(entry)
+            self._rendered_entry_count = len(entries)
+        elif rendered_count == len(entries) and entries:
+            # Same count — check if the last entry is a streaming entry that was mutated
+            last_entry = entries[-1]
+            if last_entry.type == OutputEntryType.STREAMING_TEXT:
+                panel.set_streaming_entry(last_entry)
+
+    def _sync_bottom_panel(self, mode: BottomPanelMode) -> None:
+        """Switch the bottom panel between text input, list, and streaming."""
+        try:
+            text_container = self.query_one("#text-input-container")
+            list_container = self.query_one("#list-selection-container")
+        except NoMatches:
+            return
+
+        if mode == BottomPanelMode.TEXT_INPUT:
+            text_container.display = True
+            list_container.display = False
+            # Restore focus to text input
+            try:
+                text_input = self.query_one("#text-input", HarnessTextInput)
+                text_input.focus_input()
+            except NoMatches:
+                pass
+        elif mode == BottomPanelMode.LIST_SELECTION:
+            text_container.display = False
+            list_container.display = True
+            self._sync_list_selection()
+        elif mode == BottomPanelMode.STREAMING:
+            text_container.display = True
+            list_container.display = False
+
+    def _sync_list_selection(self) -> None:
+        """Sync the list selection widget with state."""
+        try:
+            list_widget = self.query_one("#list-selection", HarnessListSelection)
+        except NoMatches:
+            return
+
+        state = self._app_state
+        list_widget.title = state.list_selection_title or ""
+        list_widget.options = list(state.list_selection_options)
+        list_widget.allow_custom_text = state.list_selection_custom_text_placeholder is not None
+
+        if state.list_selection_custom_text_placeholder:
+            try:
+                custom_input = list_widget.query_one("#custom-input", Input)
+                custom_input.placeholder = state.list_selection_custom_text_placeholder
+            except Exception:
+                pass
+
+        # Focus the option list so keyboard navigation works immediately
+        list_widget.focus_list()
+
+    def _sync_status_bar(self) -> None:
+        """Sync the status bar with state."""
+        try:
+            status = self.query_one("#status-bar", AgentStatus)
+        except NoMatches:
+            return
+
+        state = self._app_state
+        status.show_spinner = state.show_spinner
+        status.usage_text = state.usage_text or ""
+
+    def _sync_mode_help(self) -> None:
+        """Sync the mode/help display and rule colors with state."""
+        try:
+            mode_help = self.query_one("#mode-help", AgentModeAndHelp)
+        except NoMatches:
+            return
+
+        state = self._app_state
+        mode_help.mode = state.mode_text or ""
+        mode_help.mode_color = state.mode_color or "blue"
+        mode_help.help_text = state.help_text or ""
+
+        # Sync rule colors to match mode
+        color = state.mode_color or "cyan"
+        try:
+            top_rule = self.query_one("#top-rule", PromptRule)
+            top_rule.rule_color = color
+        except NoMatches:
+            pass
+
+        try:
+            bottom_rule = self.query_one("#bottom-rule", PromptRule)
+            bottom_rule.rule_color = color
+        except NoMatches:
+            pass
+
+    def _sync_chrome_visibility(self, visible: bool) -> None:
+        """Show or hide chrome elements (status bar, mode/help).
+
+        During list selection mode, these are hidden to give more vertical
+        space to the scroll panel and list picker.
+
+        Args:
+            visible: Whether chrome elements should be visible.
+        """
+        import contextlib
+
+        with contextlib.suppress(NoMatches):
+            self.query_one("#status-bar", AgentStatus).display = visible
+        with contextlib.suppress(NoMatches):
+            self.query_one("#mode-help", AgentModeAndHelp).display = visible
+
+    # --- Rendering count tracking ---
+
+    _rendered_entry_count: int = 0

python/samples/02-agents/harness/console/app_state.py

@@ -0,0 +1,260 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""Application state and core data types for the harness console.
+
+This module defines enums, dataclasses, follow-up action types, and the
+HarnessAppState dataclass which holds all UI state that may change during
+application execution. The state driver mutates this state to coordinate
+between the agent runner and the Textual UI components.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from agent_framework import Message
+
+    from .state_driver import IUXStateDriver
+
+
+# region Enums
+
+
+class OutputEntryType(Enum):
+    """Type of output entry in the console conversation."""
+
+    USER_INPUT = "user_input"
+    """User input echo (e.g., 'You: hello')."""
+
+    STREAMING_TEXT = "streaming_text"
+    """In-progress streaming text from the agent (accumulated chunk by chunk)."""
+
+    INFO_LINE = "info_line"
+    """Informational line (tool calls, errors, usage, approval requests, etc.)."""
+
+    STREAM_FOOTER = "stream_footer"
+    """Stream footer (e.g., '(no text response from agent)')."""
+
+    PENDING_MESSAGE = "pending_message"
+    """Pending injected message notification."""
+
+
+class BottomPanelMode(Enum):
+    """Mode of the bottom panel UI."""
+
+    TEXT_INPUT = "text_input"
+    """Show text input for user messages."""
+
+    LIST_SELECTION = "list_selection"
+    """Show choice list for user selection."""
+
+    STREAMING = "streaming"
+    """Show 'streaming...' indicator while agent is generating."""
+
+
+# endregion
+
+# region Output Entry
+
+
+@dataclass
+class OutputEntry:
+    """A single output entry in the console conversation history.
+
+    Used internally by the state driver to track conversation output,
+    including streaming text, tool calls, errors, and user input echoes.
+
+    Args:
+        type: The type of output entry.
+        text: The text content of the entry.
+        color: Optional Rich color string (e.g., "cyan", "red", "dim").
+    """
+
+    type: OutputEntryType
+    text: str
+    color: str | None = None
+
+
+# endregion
+
+# region Follow-Up Actions
+
+
+class FollowUpAction:
+    """Base class for follow-up actions returned by observers.
+
+    Follow-up actions describe either a question to ask the user
+    (via FollowUpQuestion subclasses) or a message to add directly
+    to the next agent input (FollowUpMessage).
+    """
+
+    pass
+
+
+@dataclass
+class FollowUpQuestion(FollowUpAction):
+    """A question to ask the user with a continuation.
+
+    The continuation delegate is invoked with the user's answer and the
+    UX state driver, and returns an optional Message to add to the next
+    agent invocation.
+
+    Args:
+        prompt: The question text shown to the user.
+        continuation: Async function invoked with the user's answer and state driver.
+            Returns an optional Message to add to the next agent input.
+    """
+
+    prompt: str
+    continuation: Callable[[str, IUXStateDriver], Awaitable[Message | None]]
+
+
+@dataclass
+class TextFollowUpQuestion(FollowUpQuestion):
+    """A free-form text question.
+
+    The user may type any response. This is the base FollowUpQuestion type
+    with no additional constraints.
+    """
+
+    pass
+
+
+@dataclass
+class ChoiceFollowUpQuestion(FollowUpQuestion):
+    """A multiple choice question.
+
+    The user picks from the provided choices, with an optional ability to
+    enter custom text when allow_custom_text is True.
+
+    Args:
+        prompt: The question text shown to the user.
+        choices: List of pre-defined choices.
+        allow_custom_text: If True, the user may type a custom response in
+            addition to the listed choices.
+        continuation: Async function invoked with the user's choice/text and
+            state driver. Returns an optional Message to add to the next agent input.
+    """
+
+    choices: list[str]
+    allow_custom_text: bool = False
+
+
+@dataclass
+class FollowUpMessage(FollowUpAction):
+    """A message to add directly to the next agent invocation without prompting.
+
+    Used when an observer wants to inject a message into the conversation
+    without user interaction (e.g., automatic tool results, system messages).
+
+    Args:
+        message: The Message to add to the conversation.
+    """
+
+    message: Message
+
+
+# endregion
+
+# region Application State
+
+
+@dataclass
+class HarnessAppState:
+    """All UI state for the harness console application.
+
+    This state is mutated by the UX state driver and read by the Textual
+    app to update the UI.
+    """
+
+    # --- Bottom panel mode ---
+
+    mode: BottomPanelMode = BottomPanelMode.TEXT_INPUT
+    """Which component is shown in the bottom panel."""
+
+    # --- Follow-up question queue ---
+
+    pending_questions: list[FollowUpQuestion] = field(default_factory=list)
+    """Queue of follow-up questions waiting for user answers.
+
+    The head ([0]) is the question currently being displayed; subsequent items
+    are dispatched in order as each is answered.
+    """
+
+    accumulated_follow_up_responses: list[Message] = field(default_factory=list)
+    """Accumulated follow-up response messages collected during the current agent turn.
+
+    Both direct FollowUpMessages emitted by observers and continuation results
+    from answered questions. Consumed by the runner via take_follow_up_responses().
+    """
+
+    # --- Text input (active in TextInput / Streaming modes) ---
+
+    prompt: str = "> "
+    """The prompt string for text input mode."""
+
+    placeholder: str = ""
+    """Placeholder text shown when the input is empty."""
+
+    input_text: str = ""
+    """The current input text being typed."""
+
+    input_enabled: bool = True
+    """Whether input is enabled (disabled during streaming without injection)."""
+
+    streaming_prompt: str = "(agent is running...)"
+    """The prompt to show during streaming when input is disabled."""
+
+    # --- List selection (active in ListSelection mode) ---
+
+    list_selection_title: str | None = None
+    """Title text displayed above the list selection."""
+
+    list_selection_options: list[str] = field(default_factory=list)
+    """The list selection options."""
+
+    list_selection_index: int = 0
+    """The highlighted option index in list selection mode."""
+
+    list_selection_custom_text_placeholder: str | None = None
+    """Placeholder text for the custom text input option in the list."""
+
+    list_selection_custom_input_text: str = ""
+    """Current text being typed into the list's custom text option."""
+
+    # --- Scroll / output area ---
+
+    output_entries: list[OutputEntry] = field(default_factory=list)
+    """Output entries in the scroll area conversation history."""
+
+    queued_items: list[str] = field(default_factory=list)
+    """Queued input items to display (pending injected messages)."""
+
+    # --- Agent mode + status display ---
+
+    mode_color: str | None = None
+    """Rich color string for the rule borders and mode label."""
+
+    mode_text: str | None = None
+    """Current mode name displayed (e.g., 'plan', 'execute')."""
+
+    help_text: str | None = None
+    """Help text displayed below the bottom rule (available commands)."""
+
+    show_spinner: bool = False
+    """Whether the agent status spinner is visible."""
+
+    usage_text: str | None = None
+    """Formatted token usage text to display in the status bar."""
+
+    # --- Command handler signals ---
+
+    shutdown_requested: bool = False
+    """Set to True when /exit is invoked; the app should exit."""
+
+    replaced_session: object | None = None
+    """When set, the app should swap its session to this AgentSession."""

python/samples/02-agents/harness/console/commands/__init__.py

@@ -0,0 +1,65 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""Command handler package for the harness console.
+
+Provides slash-command handling (e.g., /exit, /mode, /todos, /session-export)
+that intercepts user input before it reaches the agent.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from .base import CommandHandler
+from .exit_handler import ExitCommandHandler
+from .mode_handler import ModeCommandHandler
+from .session_handler import SessionCommandHandler
+from .todo_handler import TodoCommandHandler
+
+if TYPE_CHECKING:
+    from agent_framework import Agent
+
+__all__ = [
+    "CommandHandler",
+    "ExitCommandHandler",
+    "ModeCommandHandler",
+    "SessionCommandHandler",
+    "TodoCommandHandler",
+    "build_default_command_handlers",
+]
+
+
+def build_default_command_handlers(
+    agent: Agent,
+    *,
+    mode_colors: dict[str, str] | None = None,
+) -> list[CommandHandler]:
+    """Build the default set of command handlers by inspecting the agent.
+
+    Auto-detects TodoProvider and AgentModeProvider from the agent's
+    context_providers list.
+
+    Args:
+        agent: The agent to inspect for providers.
+        mode_colors: Optional mapping of mode names to Rich color strings.
+
+    Returns:
+        List of command handlers in evaluation order.
+    """
+    from agent_framework import AgentModeProvider, TodoProvider
+
+    todo_provider: TodoProvider | None = None
+    mode_provider: AgentModeProvider | None = None
+
+    for provider in getattr(agent, "context_providers", []):
+        if isinstance(provider, TodoProvider) and todo_provider is None:
+            todo_provider = provider
+        elif isinstance(provider, AgentModeProvider) and mode_provider is None:
+            mode_provider = provider
+
+    return [
+        ExitCommandHandler(),
+        TodoCommandHandler(todo_provider),
+        ModeCommandHandler(mode_provider, mode_colors),
+        SessionCommandHandler(),
+    ]

python/samples/02-agents/harness/console/commands/base.py

@@ -0,0 +1,58 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""Abstract base class for console command handlers.
+
+Command handlers intercept user input starting with '/' and execute
+local commands before input reaches the agent. They are checked in order;
+the first handler that accepts the input prevents further handlers from
+being checked.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from agent_framework import AgentSession
+
+    from ..state_driver import IUXStateDriver
+
+
+class CommandHandler(ABC):
+    """Base class for console command handlers.
+
+    Subclasses implement get_help_text() for the mode bar and
+    try_handle() to intercept matching commands.
+    """
+
+    @abstractmethod
+    def get_help_text(self) -> str | None:
+        """Get the help text for this command.
+
+        Displayed in the mode-and-help bar. Return None if the
+        command is not currently available.
+
+        Returns:
+            Help text like '/todos (show todo list)', or None.
+        """
+        ...
+
+    @abstractmethod
+    async def try_handle(
+        self,
+        user_input: str,
+        session: AgentSession,
+        ux: IUXStateDriver,
+    ) -> bool:
+        """Attempt to handle the given user input.
+
+        Args:
+            user_input: The raw user input string.
+            session: The current agent session.
+            ux: The UX state driver for rendering output.
+
+        Returns:
+            True if this handler handled the input; False otherwise.
+        """
+        ...

python/samples/02-agents/harness/console/commands/exit_handler.py

@@ -0,0 +1,35 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""Exit command handler — /exit to quit the console."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from .base import CommandHandler
+
+if TYPE_CHECKING:
+    from agent_framework import AgentSession
+
+    from ..state_driver import IUXStateDriver
+
+
+class ExitCommandHandler(CommandHandler):
+    """Handle the /exit command to shut down the console application."""
+
+    def get_help_text(self) -> str | None:
+        """Return help text for the exit command."""
+        return "/exit (quit)"
+
+    async def try_handle(
+        self,
+        user_input: str,
+        session: AgentSession,
+        ux: IUXStateDriver,
+    ) -> bool:
+        """Handle /exit by requesting shutdown."""
+        if user_input.strip().lower() != "/exit":
+            return False
+
+        ux.request_shutdown()
+        return True

python/samples/02-agents/harness/console/commands/mode_handler.py

@@ -0,0 +1,81 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""Mode command handler — /mode to show or switch agent mode."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from .base import CommandHandler
+
+if TYPE_CHECKING:
+    from agent_framework import AgentModeProvider, AgentSession
+
+    from ..state_driver import IUXStateDriver
+
+
+class ModeCommandHandler(CommandHandler):
+    """Handle the /mode command to display or switch the current agent mode."""
+
+    def __init__(
+        self,
+        mode_provider: AgentModeProvider | None,
+        mode_colors: dict[str, str] | None = None,
+    ) -> None:
+        """Initialize with mode provider and color mapping.
+
+        Args:
+            mode_provider: The mode provider, or None if not available.
+            mode_colors: Optional mapping of mode names to Rich color strings.
+        """
+        self._mode_provider = mode_provider
+        self._mode_colors = mode_colors or {}
+
+    def get_help_text(self) -> str | None:
+        """Return help text, or None if mode provider is unavailable."""
+        if self._mode_provider is None:
+            return None
+        return "/mode [plan|execute] (show or switch mode)"
+
+    async def try_handle(
+        self,
+        user_input: str,
+        session: AgentSession,
+        ux: IUXStateDriver,
+    ) -> bool:
+        """Handle /mode [name] command."""
+        stripped = user_input.strip()
+        lower = stripped.lower()
+
+        if not (lower == "/mode" or lower.startswith("/mode ")):
+            return False
+
+        if self._mode_provider is None:
+            ux.append_info_line("AgentModeProvider is not available.")
+            return True
+
+        parts = stripped.split(None, 1)
+        if len(parts) < 2:
+            # Show current mode
+            from agent_framework import get_agent_mode
+
+            current = get_agent_mode(session)
+            ux.append_info_line(f"Current mode: {current}")
+            return True
+
+        # Switch mode
+        new_mode = parts[1].strip()
+        try:
+            from agent_framework import set_agent_mode
+
+            normalized = set_agent_mode(session, new_mode)
+            color = self._mode_colors.get(normalized)
+            ux.set_mode(normalized, color)
+            ux.append_info_line(
+                f"Switched to {normalized} mode.",
+                color=color,
+            )
+        except ValueError as ex:
+            ux.append_info_line(str(ex), color="red")
+
+        return True

python/samples/02-agents/harness/console/commands/session_handler.py

@@ -0,0 +1,107 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""Session command handler — /session-export and /session-import."""
+
+from __future__ import annotations
+
+import json
+from typing import TYPE_CHECKING
+
+from .base import CommandHandler
+
+if TYPE_CHECKING:
+    from agent_framework import AgentSession
+
+    from ..state_driver import IUXStateDriver
+
+
+class SessionCommandHandler(CommandHandler):
+    """Handle /session-export and /session-import commands."""
+
+    def get_help_text(self) -> str | None:
+        """Return help text for session commands."""
+        return "/session-export <file> | /session-import <file>"
+
+    async def try_handle(
+        self,
+        user_input: str,
+        session: AgentSession,
+        ux: IUXStateDriver,
+    ) -> bool:
+        """Handle session export/import commands."""
+        stripped = user_input.strip()
+        command = stripped.split(None, 1)[0].lower() if stripped else ""
+
+        if command == "/session-export":
+            await self._handle_export(stripped, session, ux)
+            return True
+
+        if command == "/session-import":
+            await self._handle_import(stripped, ux)
+            return True
+
+        return False
+
+    async def _handle_export(
+        self,
+        user_input: str,
+        session: AgentSession,
+        ux: IUXStateDriver,
+    ) -> None:
+        """Export the current session to a JSON file."""
+        parts = user_input.split(None, 1)
+        if len(parts) < 2:
+            ux.append_info_line("Usage: /session-export <filename>")
+            return
+
+        filename = parts[1].strip()
+        try:
+            serialized = session.to_dict()
+            json_str = json.dumps(serialized, indent=2)
+            self._write_file(filename, json_str)
+            ux.append_info_line(f"Session exported to {filename}")
+        except Exception as ex:
+            ux.append_info_line(
+                f"Failed to export session to {filename}: {ex}",
+                color="red",
+            )
+
+    async def _handle_import(
+        self,
+        user_input: str,
+        ux: IUXStateDriver,
+    ) -> None:
+        """Import a session from a JSON file."""
+        parts = user_input.split(None, 1)
+        if len(parts) < 2:
+            ux.append_info_line("Usage: /session-import <filename>")
+            return
+
+        filename = parts[1].strip()
+        try:
+            from agent_framework import AgentSession
+
+            json_str = self._read_file(filename)
+            data = json.loads(json_str)
+            new_session = AgentSession.from_dict(data)
+            ux.replace_session(new_session)
+            ux.append_info_line(f"Session imported from {filename}")
+        except FileNotFoundError:
+            ux.append_info_line(f"File not found: {filename}", color="red")
+        except Exception as ex:
+            ux.append_info_line(
+                f"Failed to import session from {filename}: {ex}",
+                color="red",
+            )
+
+    @staticmethod
+    def _write_file(filename: str, content: str) -> None:
+        """Write content to a file (sync helper to satisfy ASYNC230)."""
+        with open(filename, "w", encoding="utf-8") as f:  # noqa: ASYNC230
+            f.write(content)
+
+    @staticmethod
+    def _read_file(filename: str) -> str:
+        """Read content from a file (sync helper to satisfy ASYNC230)."""
+        with open(filename, encoding="utf-8") as f:  # noqa: ASYNC230
+            return f.read()

python/samples/02-agents/harness/console/commands/todo_handler.py

@@ -0,0 +1,66 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""Todo command handler — /todos to display the todo list."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from .base import CommandHandler
+
+if TYPE_CHECKING:
+    from agent_framework import AgentSession, TodoProvider
+
+    from ..state_driver import IUXStateDriver
+
+
+class TodoCommandHandler(CommandHandler):
+    """Handle the /todos command to display the current todo list."""
+
+    def __init__(self, todo_provider: TodoProvider | None) -> None:
+        """Initialize with the todo provider.
+
+        Args:
+            todo_provider: The todo provider, or None if not available.
+        """
+        self._todo_provider = todo_provider
+
+    def get_help_text(self) -> str | None:
+        """Return help text, or None if todo provider is unavailable."""
+        if self._todo_provider is None:
+            return None
+        return "/todos (show todo list)"
+
+    async def try_handle(
+        self,
+        user_input: str,
+        session: AgentSession,
+        ux: IUXStateDriver,
+    ) -> bool:
+        """Handle /todos by displaying the todo list."""
+        if user_input.strip().lower() != "/todos":
+            return False
+
+        if self._todo_provider is None:
+            ux.append_info_line("TodoProvider is not available.")
+            return True
+
+        todos = await self._todo_provider.store.load_items(
+            session, source_id=self._todo_provider.source_id
+        )
+
+        if not todos:
+            ux.append_info_line("No todos yet.")
+            return True
+
+        ux.append_info_line("── Todo List ──")
+        for item in todos:
+            status = "✓" if item.is_complete else "○"
+            color = "dim" if item.is_complete else None
+            description = f" — {item.description}" if item.description else ""
+            ux.append_info_line(
+                f"[{status}] #{item.id} {item.title}{description}",
+                color=color,
+            )
+
+        return True

python/samples/02-agents/harness/console/components/__init__.py

@@ -0,0 +1,23 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""UI components for the harness console.
+
+This module provides Textual widgets for building the harness console UI,
+including status displays, input fields, choice selectors, and scrolling panels.
+"""
+
+from .agent_status import AgentStatus
+from .list_selection import HarnessListSelection
+from .mode_help import AgentModeAndHelp
+from .prompt_rule import PromptRule
+from .scroll_panel import HarnessScrollPanel
+from .text_input import HarnessTextInput
+
+__all__ = [
+    "AgentStatus",
+    "AgentModeAndHelp",
+    "HarnessListSelection",
+    "PromptRule",
+    "HarnessScrollPanel",
+    "HarnessTextInput",
+]

python/samples/02-agents/harness/console/components/agent_status.py

@@ -0,0 +1,66 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""Agent status widget with spinner animation and usage statistics."""
+
+from __future__ import annotations
+
+from textual.reactive import reactive
+from textual.widgets import Static
+
+
+class AgentStatus(Static):
+    """Agent status bar with animated spinner and token usage display.
+
+    Displays an animated braille pattern spinner when the agent is active,
+    along with token usage statistics. The component automatically updates
+    the spinner animation at ~10fps for smooth visual feedback.
+
+    Attributes:
+        show_spinner: Whether to display the animated spinner.
+        usage_text: Token usage text to display (e.g., "1.2K in / 856 out").
+    """
+
+    # Braille pattern spinner frames for smooth animation
+    SPINNER_FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"]
+
+    show_spinner: reactive[bool] = reactive(False)
+    usage_text: reactive[str] = reactive("")
+
+    def __init__(self, **kwargs) -> None:
+        """Initialize the agent status widget."""
+        super().__init__(**kwargs)
+        self._spinner_index = 0
+
+    def on_mount(self) -> None:
+        """Start the spinner animation timer when the widget is mounted."""
+        # Update spinner at ~10fps (every 0.1 seconds)
+        self.set_interval(0.1, self._advance_spinner)
+
+    def _advance_spinner(self) -> None:
+        """Advance the spinner to the next frame."""
+        if self.show_spinner:
+            self._spinner_index = (self._spinner_index + 1) % len(self.SPINNER_FRAMES)
+            self.refresh()
+
+    def render(self) -> str:
+        """Render the status bar with spinner and usage text.
+
+        Returns:
+            Formatted string with Rich markup for spinner and usage display.
+        """
+        if not self.show_spinner and not self.usage_text:
+            return ""
+
+        parts = []
+
+        if self.show_spinner:
+            frame = self.SPINNER_FRAMES[self._spinner_index]
+            parts.append(f"[cyan]{frame}[/cyan]")
+        else:
+            # Keep consistent spacing when spinner is off
+            parts.append(" ")
+
+        if self.usage_text:
+            parts.append(f"[dim]{self.usage_text}[/dim]")
+
+        return " ".join(parts)

python/samples/02-agents/harness/console/components/list_selection.py

@@ -0,0 +1,269 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""List selection widget with optional custom text input."""
+
+from __future__ import annotations
+
+from textual import on
+from textual.app import ComposeResult
+from textual.binding import Binding
+from textual.containers import Container
+from textual.css.query import NoMatches
+from textual.events import Key
+from textual.message import Message
+from textual.reactive import reactive
+from textual.widget import Widget
+from textual.widgets import Input, Label, OptionList
+from textual.widgets.option_list import Option
+
+
+class HarnessListSelection(Widget):
+    """List selection widget with numbered choices and optional custom text input.
+
+    Displays a title, a list of numbered choices that can be selected via
+    keyboard navigation or number keys (1-9), and an optional custom text
+    input field at the bottom.
+
+    All child nodes (title label, option list, custom input) are always
+    present in the DOM; visibility is toggled via reactive watchers.
+
+    Navigation:
+    - Down arrow on last list item moves focus to the custom text input
+    - Up arrow on the custom text input moves focus back to the option list
+    - When custom input has focus, the option list highlight is cleared
+
+    Attributes:
+        title: The title text displayed above the options.
+        options: List of option strings to display.
+        allow_custom_text: Whether to show a custom text input field.
+    """
+
+    DEFAULT_CSS = """
+    HarnessListSelection {
+        height: auto;
+        max-height: 12;
+    }
+
+    HarnessListSelection .list-selection-container {
+        height: auto;
+    }
+
+    HarnessListSelection #selection-title {
+        height: auto;
+        color: $text;
+        text-style: bold;
+        padding: 0 0 0 0;
+    }
+
+    HarnessListSelection #option-list {
+        height: auto;
+        max-height: 8;
+        border: none;
+        padding: 0;
+    }
+
+    HarnessListSelection #custom-input {
+        height: auto;
+        min-height: 1;
+        margin-top: 0;
+        border: tall transparent;
+    }
+
+    HarnessListSelection #custom-input:focus {
+        border: tall $accent;
+    }
+    """
+
+    BINDINGS = [
+        Binding("1", "select_option(0)", "Select option 1", show=False),
+        Binding("2", "select_option(1)", "Select option 2", show=False),
+        Binding("3", "select_option(2)", "Select option 3", show=False),
+        Binding("4", "select_option(3)", "Select option 4", show=False),
+        Binding("5", "select_option(4)", "Select option 5", show=False),
+        Binding("6", "select_option(5)", "Select option 6", show=False),
+        Binding("7", "select_option(6)", "Select option 7", show=False),
+        Binding("8", "select_option(7)", "Select option 8", show=False),
+        Binding("9", "select_option(8)", "Select option 9", show=False),
+    ]
+
+    title: reactive[str] = reactive("")
+    options: reactive[list[str]] = reactive(list, always_update=True)
+    allow_custom_text: reactive[bool] = reactive(False)
+
+    class Selected(Message):
+        """Message sent when an option is selected.
+
+        Attributes:
+            value: The selected option text or custom text.
+        """
+
+        def __init__(self, value: str) -> None:
+            """Initialize the Selected message.
+
+            Args:
+                value: The selected option text or custom text.
+            """
+            self.value = value
+            super().__init__()
+
+    def compose(self) -> ComposeResult:
+        """Compose the widget — all nodes are always present.
+
+        Yields:
+            Title label (hidden if empty), option list, custom input (hidden by default).
+        """
+        with Container(classes="list-selection-container"):
+            yield Label("", id="selection-title")
+            yield OptionList(id="option-list")
+            yield Input(
+                placeholder="Or type a custom response...",
+                id="custom-input",
+            )
+
+    def on_mount(self) -> None:
+        """Configure initial visibility after mount."""
+        title_label = self.query_one("#selection-title", Label)
+        title_label.display = bool(self.title)
+
+        custom_input = self.query_one("#custom-input", Input)
+        custom_input.display = self.allow_custom_text
+
+        self._update_options()
+
+    def on_key(self, event: Key) -> None:
+        """Handle key navigation between option list and custom input.
+
+        Args:
+            event: The key event.
+        """
+        if not self.allow_custom_text:
+            return
+
+        option_list = self.query_one("#option-list", OptionList)
+        custom_input = self.query_one("#custom-input", Input)
+
+        # Down arrow on last item → move to custom input
+        if event.key == "down" and option_list.has_focus:
+            last_index = option_list.option_count - 1
+            if last_index >= 0 and option_list.highlighted == last_index:
+                option_list.highlighted = None  # type: ignore[assignment]
+                custom_input.focus()
+                event.prevent_default()
+                event.stop()
+
+        # Up arrow on custom input → move back to option list (last item)
+        elif event.key == "up" and custom_input.has_focus:
+            last_index = option_list.option_count - 1
+            if last_index >= 0:
+                option_list.highlighted = last_index
+            option_list.focus()
+            event.prevent_default()
+            event.stop()
+
+    @on(Input.Changed, "#custom-input")
+    def on_custom_input_focused_or_changed(self, event: Input.Changed) -> None:
+        """Clear option list highlight when user is typing in custom input.
+
+        Args:
+            event: The input changed event.
+        """
+        option_list = self.query_one("#option-list", OptionList)
+        option_list.highlighted = None  # type: ignore[assignment]
+
+    def watch_title(self, new_title: str) -> None:
+        """Update the title label when the title changes.
+
+        Args:
+            new_title: The new title text.
+        """
+        try:
+            label = self.query_one("#selection-title", Label)
+            label.update(new_title)
+            label.display = bool(new_title)
+        except NoMatches:
+            pass
+
+    def watch_options(self, new_options: list[str]) -> None:
+        """Update the option list when options change.
+
+        Args:
+            new_options: The new list of options.
+        """
+        import contextlib
+
+        with contextlib.suppress(NoMatches):
+            self._update_options()
+
+    def watch_allow_custom_text(self, allow: bool) -> None:
+        """Show/hide the custom input field.
+
+        Args:
+            allow: Whether to show the custom text input.
+        """
+        try:
+            custom_input = self.query_one("#custom-input", Input)
+            custom_input.display = allow
+        except NoMatches:
+            pass
+
+    def _update_options(self) -> None:
+        """Update the OptionList with numbered options."""
+        try:
+            option_list = self.query_one("#option-list", OptionList)
+            option_list.clear_options()
+
+            for i, option_text in enumerate(self.options):
+                display_text = f"{i + 1}. {option_text}" if i < 9 else f"   {option_text}"
+                option_list.add_option(Option(display_text, id=str(i)))
+        except NoMatches:
+            pass
+
+    @on(OptionList.OptionSelected)
+    def on_option_selected(self, event: OptionList.OptionSelected) -> None:
+        """Handle option selection from the list.
+
+        Args:
+            event: The OptionList.OptionSelected event.
+        """
+        option_index = int(event.option.id or "0")
+        if 0 <= option_index < len(self.options):
+            selected_value = self.options[option_index]
+            self.post_message(self.Selected(selected_value))
+
+    @on(Input.Submitted)
+    def on_input_submitted(self, event: Input.Submitted) -> None:
+        """Handle custom text input submission.
+
+        Args:
+            event: The Input.Submitted event.
+        """
+        if self.allow_custom_text and event.value:
+            self.post_message(self.Selected(event.value))
+            event.input.clear()
+
+    def action_select_option(self, index: int) -> None:
+        """Select an option by index (0-based).
+
+        Args:
+            index: The option index to select.
+        """
+        if 0 <= index < len(self.options):
+            selected_value = self.options[index]
+            self.post_message(self.Selected(selected_value))
+
+    def focus_list(self) -> None:
+        """Focus the option list."""
+        try:
+            option_list = self.query_one("#option-list", OptionList)
+            option_list.focus()
+        except NoMatches:
+            pass
+
+    def focus_custom_input(self) -> None:
+        """Focus the custom text input field."""
+        if self.allow_custom_text:
+            try:
+                custom_input = self.query_one("#custom-input", Input)
+                custom_input.focus()
+            except NoMatches:
+                pass

python/samples/02-agents/harness/console/components/mode_help.py

@@ -0,0 +1,48 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""Agent mode and help text display widget."""
+
+from __future__ import annotations
+
+from rich.text import Text
+from textual.reactive import reactive
+from textual.widgets import Static
+
+
+class AgentModeAndHelp(Static):
+    """Widget displaying the current agent mode and help text.
+
+    Shows the current agent mode (e.g., "plan", "execute") in a colored label,
+    followed by available commands and help text in a dimmed style. Used in
+    the fixed bottom area of the console.
+
+    Attributes:
+        mode: Current mode name (e.g., "plan", "execute"), or None if no mode.
+        mode_color: Rich color string for the mode label (e.g., "yellow", "green").
+        help_text: Help text to display (e.g., "/exit to quit, /mode to switch").
+    """
+
+    mode: reactive[str | None] = reactive(None)
+    mode_color: reactive[str] = reactive("yellow")
+    help_text: reactive[str] = reactive("")
+
+    def render(self) -> Text:
+        """Render the mode indicator and help text.
+
+        Returns:
+            Rich Text object with styled mode and help display.
+        """
+        result = Text()
+
+        if self.mode:
+            result.append(f"[{self.mode}]", style=self.mode_color)
+
+        if self.help_text:
+            if self.mode:
+                result.append("  ")
+            result.append(self.help_text, style="dim")
+
+        if not result.plain:
+            result.append(" ")
+
+        return result

python/samples/02-agents/harness/console/components/prompt_rule.py

@@ -0,0 +1,31 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""Mode-colored horizontal rule."""
+
+from __future__ import annotations
+
+from textual.reactive import reactive
+from textual.widgets import Static
+
+
+class PromptRule(Static):
+    """A full-width horizontal rule colored by the current agent mode.
+
+    Renders a line of '─' characters across the terminal width,
+    colored to match the current mode (e.g., cyan for plan, green for execute).
+
+    Attributes:
+        rule_color: Rich color string for the rule (e.g., "cyan", "green").
+    """
+
+    rule_color: reactive[str] = reactive("cyan")
+
+    def render(self) -> str:
+        """Render the horizontal rule.
+
+        Returns:
+            Formatted string with Rich markup.
+        """
+        color = self.rule_color
+        width = self.size.width or 80
+        return f"[{color}]{'─' * width}[/{color}]"

python/samples/02-agents/harness/console/components/scroll_panel.py

@@ -0,0 +1,127 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""Scrolling panel for conversation history display."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from textual.widgets import RichLog
+
+if TYPE_CHECKING:
+    from ..app_state import OutputEntry
+
+
+class HarnessScrollPanel(RichLog):
+    """Scrolling panel for displaying conversation history.
+
+    Uses Textual's RichLog widget for efficient append-only rendering with
+    Rich text formatting support. Automatically scrolls to the bottom when
+    new entries are added.
+
+    For streaming text, the panel uses a truncate-and-rewrite strategy: it
+    tracks where streaming began in the RichLog lines list, and on each update
+    truncates back to that point and rewrites the full accumulated text as a
+    single write. This ensures consistent rendering without line-break artifacts
+    between streamed chunks.
+    """
+
+    def __init__(self, **kwargs) -> None:
+        """Initialize the scroll panel.
+
+        Args:
+            **kwargs: Additional arguments passed to RichLog.
+        """
+        super().__init__(
+            **kwargs,
+            auto_scroll=True,  # Automatically scroll to bottom
+            wrap=True,  # Wrap long lines instead of horizontal scroll
+            markup=True,  # Enable Rich markup
+            highlight=True,  # Enable syntax highlighting
+        )
+        self._entries: list[OutputEntry] = []
+        self._is_streaming = False
+        self._streaming_line_start: int = 0
+
+    def append_entry(self, entry: OutputEntry) -> None:
+        """Append a new output entry to the conversation history.
+
+        Args:
+            entry: The output entry to append.
+        """
+        self._entries.append(entry)
+        text = self._format_entry(entry)
+        self.write(text)
+
+    def set_streaming_entry(self, entry: OutputEntry) -> None:
+        """Set or update the current streaming entry.
+
+        On each update, truncates the RichLog back to where streaming
+        started, then rewrites the full streaming text as a single block.
+        This ensures no spurious line breaks between chunks while avoiding
+        a full rewrite of all entries.
+
+        Args:
+            entry: The streaming entry (will be mutated externally).
+        """
+        if not self._is_streaming:
+            # First streaming chunk — record where streaming lines begin
+            self._is_streaming = True
+            self._entries.append(entry)
+            self._streaming_line_start = len(self.lines)
+
+        # Truncate lines back to where streaming started
+        if len(self.lines) > self._streaming_line_start:
+            del self.lines[self._streaming_line_start:]
+            from textual.geometry import Size
+
+            self.virtual_size = Size(self._widest_line_width, len(self.lines))
+
+        # Write full streaming text as a single renderable
+        formatted = self._format_text(entry.text, entry.color)
+        self.write(formatted)
+
+    def end_streaming(self) -> None:
+        """End the current streaming mode."""
+        if self._is_streaming:
+            self._is_streaming = False
+            self._streaming_line_start = 0
+
+    def _rewrite_all(self) -> None:
+        """Clear and rewrite all entries from scratch."""
+        self.clear()
+        for entry in self._entries:
+            self.write(self._format_entry(entry))
+
+    def _format_entry(self, entry: OutputEntry) -> str:
+        """Format an output entry with Rich markup.
+
+        Args:
+            entry: The entry to format.
+
+        Returns:
+            Formatted string with Rich markup for color and styling.
+        """
+        return self._format_text(entry.text, entry.color)
+
+    @staticmethod
+    def _format_text(text: str, color: str | None) -> str:
+        """Format text with optional Rich color markup.
+
+        Args:
+            text: The text to format.
+            color: Optional Rich color name.
+
+        Returns:
+            Formatted string.
+        """
+        if color:
+            return f"[{color}]{text}[/{color}]"
+        return text
+
+    def clear_history(self) -> None:
+        """Clear all conversation history from the panel."""
+        self._entries.clear()
+        self._is_streaming = False
+        self._streaming_line_start = 0
+        self.clear()

python/samples/02-agents/harness/console/components/text_input.py

@@ -0,0 +1,102 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""Text input widget with inline prompt for the harness console."""
+
+from __future__ import annotations
+
+from textual import on
+from textual.app import ComposeResult
+from textual.containers import Horizontal
+from textual.message import Message
+from textual.reactive import reactive
+from textual.widget import Widget
+from textual.widgets import Input, Label
+
+
+class HarnessTextInput(Widget):
+    """Text input widget with a prompt label on the left.
+
+    Displays a prompt (e.g., "> ") followed by a borderless input field.
+    Sits between the two mode-colored horizontal rules.
+
+    Attributes:
+        prompt: The prompt text displayed on the left (e.g., "> ").
+        placeholder: Placeholder text shown when the input is empty.
+    """
+
+    prompt: reactive[str] = reactive("> ")
+    placeholder: reactive[str] = reactive("")
+
+    class Submitted(Message):
+        """Message sent when the input is submitted.
+
+        Attributes:
+            value: The submitted text value.
+        """
+
+        def __init__(self, value: str) -> None:
+            """Initialize the Submitted message.
+
+            Args:
+                value: The submitted text value.
+            """
+            self.value = value
+            super().__init__()
+
+    def compose(self) -> ComposeResult:
+        """Compose the prompt label and input field.
+
+        Yields:
+            A horizontal container with the prompt and input field.
+        """
+        with Horizontal(classes="prompt-container"):
+            yield Label(self.prompt, classes="prompt-label", id="prompt-label")
+            yield Input(placeholder=self.placeholder, classes="input-field", id="input-field")
+
+    def watch_prompt(self, new_prompt: str) -> None:
+        """Update the prompt label when the prompt attribute changes.
+
+        Args:
+            new_prompt: The new prompt text.
+        """
+        try:
+            label = self.query_one("#prompt-label", Label)
+            label.update(new_prompt)
+        except Exception:
+            pass
+
+    def watch_placeholder(self, new_placeholder: str) -> None:
+        """Update the input placeholder when the placeholder attribute changes.
+
+        Args:
+            new_placeholder: The new placeholder text.
+        """
+        try:
+            input_field = self.query_one("#input-field", Input)
+            input_field.placeholder = new_placeholder
+        except Exception:
+            # Input doesn't exist yet (before compose), ignore
+            pass
+
+    @on(Input.Submitted)
+    def on_input_submitted(self, event: Input.Submitted) -> None:
+        """Handle input submission.
+
+        Clears the input field and posts a Submitted message with the value.
+
+        Args:
+            event: The Input.Submitted event.
+        """
+        value = event.value
+        event.input.clear()
+        self.post_message(self.Submitted(value))
+
+    def focus_input(self) -> None:
+        """Focus the input field."""
+        input_field = self.query_one(".input-field", Input)
+        input_field.focus()
+
+    def clear_input(self) -> None:
+        """Clear the input field."""
+        input_field = self.query_one(".input-field", Input)
+        input_field.clear()

python/samples/02-agents/harness/console/formatters.py

@@ -0,0 +1,503 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""Tool call formatters for displaying function calls in the harness console.
+
+This module provides formatters that convert raw function call content into
+human-readable display strings. Each formatter handles specific tool patterns
+(e.g., web_search, todos_*, etc.) and the FallbackToolFormatter provides
+generic formatting for any unmatched tools.
+
+Usage:
+    from harness.console.formatters import build_default_formatters, format_tool_call
+    from agent_framework import Content
+
+    call = Content.from_function_call(
+        call_id="call_1",
+        name="web_search",
+        arguments={"query": "Python async"}
+    )
+    formatters = build_default_formatters()
+    result = format_tool_call(formatters, call)  # "web_search (Python async)"
+"""
+
+from __future__ import annotations
+
+import contextlib
+import json
+from abc import ABC, abstractmethod
+from typing import Any
+
+from agent_framework import Content
+
+# region Helper Functions
+
+
+def get_argument_value(call: Content, param_name: str) -> Any:
+    """Extract an argument value from a function call.
+
+    Handles both dict and JSON string arguments.
+
+    Args:
+        call: The function call content.
+        param_name: The parameter name to extract.
+
+    Returns:
+        The argument value, or None if not found.
+    """
+    if call.arguments is None:
+        return None
+
+    if isinstance(call.arguments, str):
+        # arguments is a JSON string, parse it
+        try:
+            args_dict = json.loads(call.arguments)
+        except (json.JSONDecodeError, TypeError):
+            return None
+        if not isinstance(args_dict, dict):
+            return None
+    elif isinstance(call.arguments, dict):
+        args_dict = call.arguments
+    else:
+        return None
+
+    return args_dict.get(param_name)
+
+
+def as_int_list(value: Any) -> list[int] | None:
+    """Convert a value to a list of integers, or None if not possible.
+
+    Args:
+        value: The value to convert (should be a list).
+
+    Returns:
+        A list of integers, or None if conversion fails.
+    """
+    if not isinstance(value, list):
+        return None
+
+    result: list[int] = []
+    for item in value:
+        if isinstance(item, int):
+            result.append(item)
+        else:
+            with contextlib.suppress(ValueError, TypeError):
+                result.append(int(item))
+
+    return result if result else None
+
+
+def as_dict_list(value: Any) -> list[dict[str, Any]] | None:
+    """Convert a value to a list of dicts, or None if not possible.
+
+    Args:
+        value: The value to convert (should be a list).
+
+    Returns:
+        A list of dicts, or None if value is not a list of dicts.
+    """
+    if not isinstance(value, list):
+        return None
+
+    result: list[dict[str, Any]] = []
+    for item in value:
+        if isinstance(item, dict):
+            result.append(item)
+
+    return result if result else None
+
+
+def truncate(text: str, max_length: int) -> str:
+    """Truncate a string to the specified maximum length, appending an ellipsis if truncated.
+
+    Args:
+        text: The text to truncate.
+        max_length: The maximum length.
+
+    Returns:
+        The truncated string.
+    """
+    return text if len(text) <= max_length else text[:max_length] + "…"
+
+
+# endregion
+
+# region Base Class
+
+
+class ToolCallFormatter(ABC):
+    """Base class for tool call formatters that produce human-readable display strings
+    for function call content items shown in the console.
+    """
+
+    @abstractmethod
+    def can_format(self, call: Content) -> bool:
+        """Return True if this formatter can handle the given function call.
+
+        Args:
+            call: The function call content to check.
+
+        Returns:
+            True if this formatter should be used; otherwise False.
+        """
+        ...
+
+    @abstractmethod
+    def format_detail(self, call: Content) -> str | None:
+        """Return the detail portion of the formatted output for the given tool call,
+        or None if only the tool name should be displayed.
+
+        Args:
+            call: The function call content to format.
+
+        Returns:
+            A detail string to append after the tool name, or None.
+        """
+        ...
+
+
+# endregion
+
+# region Concrete Formatters
+
+
+class FallbackToolFormatter(ToolCallFormatter):
+    """Catch-all formatter that handles any tool not matched by a more specific formatter.
+
+    Displays a generic summary of the tool's arguments. This formatter should always be
+    placed last in the formatter list.
+    """
+
+    def can_format(self, call: Content) -> bool:
+        """Always returns True - this formatter matches everything."""
+        return True
+
+    def format_detail(self, call: Content) -> str | None:
+        """Format arguments as generic (key: value, ...) pairs."""
+        if call.arguments is None:
+            return None
+
+        # Parse arguments
+        if isinstance(call.arguments, str):
+            try:
+                args_dict = json.loads(call.arguments)
+            except (json.JSONDecodeError, TypeError):
+                return None
+        elif isinstance(call.arguments, dict):
+            args_dict = call.arguments
+        else:
+            return None
+
+        if not args_dict:
+            return None
+
+        # Build argument list
+        parts: list[str] = []
+        for key, value in args_dict.items():
+            if value is None:
+                continue
+
+            # Convert value to string
+            if isinstance(value, bool):
+                str_value = "true" if value else "false"
+            elif isinstance(value, (int, float)):
+                str_value = str(value)
+            elif isinstance(value, str):
+                str_value = value
+            else:
+                # Complex types - skip for now
+                continue
+
+            parts.append(f"{key}: {truncate(str_value, 40)}")
+
+        return f"({', '.join(parts)})" if parts else None
+
+
+class WebSearchToolFormatter(ToolCallFormatter):
+    """Formats web_search tool calls, showing the search query."""
+
+    def can_format(self, call: Content) -> bool:
+        """Match web_search tool calls."""
+        return call.name == "web_search"
+
+    def format_detail(self, call: Content) -> str | None:
+        """Extract and format the query parameter."""
+        value = get_argument_value(call, "query")
+        return f"({value})" if value else None
+
+
+class TodoToolFormatter(ToolCallFormatter):
+    """Formats todos_* tool calls with tree-view output for added items
+    and structured output for complete/remove operations.
+    """
+
+    def can_format(self, call: Content) -> bool:
+        """Match todos_* tool calls."""
+        return call.name is not None and call.name.startswith("todos_")
+
+    def format_detail(self, call: Content) -> str | None:
+        """Format based on the specific todos operation."""
+        if call.name == "todos_add":
+            return self._format_add_todos(call)
+        if call.name == "todos_complete":
+            return self._format_complete_todos(call)
+        if call.name == "todos_remove":
+            return self._format_id_list(call, "ids", "Remove")
+        return None
+
+    def _format_add_todos(self, call: Content) -> str | None:
+        """Format todos_add with tree view of titles."""
+        todos = as_dict_list(get_argument_value(call, "todos"))
+        if not todos:
+            return None
+
+        titles: list[str] = []
+        for todo in todos:
+            title = todo.get("title")
+            if title and isinstance(title, str):
+                titles.append(title)
+
+        if not titles:
+            return None
+
+        # Build tree view
+        count = len(titles)
+        plural = "s" if count != 1 else ""
+        lines = [f"({count} item{plural})"]
+        for i, title in enumerate(titles):
+            connector = "├─" if i < count - 1 else "└─"
+            lines.append(f"\n   {connector} {title}")
+
+        return "".join(lines)
+
+    def _format_complete_todos(self, call: Content) -> str | None:
+        """Format todos_complete with tree view of IDs and reasons."""
+        items = as_dict_list(get_argument_value(call, "items"))
+        if not items:
+            return None
+
+        entries: list[tuple[int, str | None]] = []
+        for item in items:
+            todo_id = item.get("id")
+            if not isinstance(todo_id, int):
+                continue
+
+            reason = item.get("reason")
+            reason_str = str(reason) if reason is not None and not isinstance(reason, str) else reason
+            entries.append((todo_id, reason_str))
+
+        if not entries:
+            return None
+
+        # Build tree view
+        lines: list[str] = []
+        for i, (todo_id, reason) in enumerate(entries):
+            connector = "├─" if i < len(entries) - 1 else "└─"
+            line = f"\n   {connector} Complete #{todo_id}"
+            if reason:
+                line += f" — {truncate(reason, 80)}"
+            lines.append(line)
+
+        return "".join(lines)
+
+    def _format_id_list(self, call: Content, param_name: str, verb: str) -> str | None:
+        """Format a list of IDs with a verb (e.g., Remove #1, Remove #2)."""
+        ids = as_int_list(get_argument_value(call, param_name))
+        if not ids:
+            return None
+
+        lines: list[str] = []
+        for i, todo_id in enumerate(ids):
+            connector = "├─" if i < len(ids) - 1 else "└─"
+            lines.append(f"\n   {connector} {verb} #{todo_id}")
+
+        return "".join(lines)
+
+
+class ModeToolFormatter(ToolCallFormatter):
+    """Formats AgentMode_* tool calls, showing the target mode for Set operations."""
+
+    def can_format(self, call: Content) -> bool:
+        """Match AgentMode_* tool calls."""
+        return call.name is not None and call.name.startswith("AgentMode_")
+
+    def format_detail(self, call: Content) -> str | None:
+        """Format based on the specific AgentMode operation."""
+        if call.name == "AgentMode_Set":
+            value = get_argument_value(call, "mode")
+            return f"({value})" if value else None
+        return None
+
+
+class BackgroundAgentToolFormatter(ToolCallFormatter):
+    """Formats BackgroundAgents_* tool calls with human-readable details
+    for task start, continue, wait, and result retrieval operations.
+    """
+
+    def can_format(self, call: Content) -> bool:
+        """Match BackgroundAgents_* tool calls."""
+        return call.name is not None and call.name.startswith("BackgroundAgents_")
+
+    def format_detail(self, call: Content) -> str | None:
+        """Format based on the specific BackgroundAgents operation."""
+        if call.name == "BackgroundAgents_StartTask":
+            return self._format_start_background_task(call)
+        if call.name == "BackgroundAgents_WaitForFirstCompletion":
+            return self._format_id_list(call, "taskIds", "Wait for")
+        if call.name == "BackgroundAgents_GetTaskResults":
+            return self._format_single_id(call, "taskId")
+        if call.name == "BackgroundAgents_ContinueTask":
+            return self._format_continue_task(call)
+        if call.name == "BackgroundAgents_ClearCompletedTask":
+            return self._format_single_id(call, "taskId")
+        return None
+
+    def _format_start_background_task(self, call: Content) -> str | None:
+        """Format StartTask with agent name and description."""
+        agent_name = get_argument_value(call, "agentName")
+        description = get_argument_value(call, "description")
+
+        if agent_name is None and description is None:
+            return None
+
+        lines: list[str] = []
+
+        if agent_name is not None and description is not None:
+            lines.append(f"\n   ├─ Agent: {agent_name}")
+            lines.append(f'\n   └─ "{truncate(description, 80)}"')
+        elif agent_name is not None:
+            lines.append(f"\n   └─ Agent: {agent_name}")
+        else:
+            lines.append(f'\n   └─ "{truncate(description, 80)}"')  # type: ignore[arg-type]
+
+        return "".join(lines)
+
+    def _format_id_list(self, call: Content, param_name: str, verb: str) -> str | None:
+        """Format a list of task IDs with a verb."""
+        ids = as_int_list(get_argument_value(call, param_name))
+        if not ids:
+            return None
+
+        lines: list[str] = []
+        for i, task_id in enumerate(ids):
+            connector = "├─" if i < len(ids) - 1 else "└─"
+            lines.append(f"\n   {connector} {verb} #{task_id}")
+
+        return "".join(lines)
+
+    def _format_single_id(self, call: Content, param_name: str) -> str | None:
+        """Format a single task ID in parentheses."""
+        task_id = get_argument_value(call, param_name)
+        if isinstance(task_id, int):
+            return f"(task #{task_id})"
+        return None
+
+    def _format_continue_task(self, call: Content) -> str | None:
+        """Format ContinueTask with task ID and optional text."""
+        task_id = get_argument_value(call, "taskId")
+        text = get_argument_value(call, "text")
+
+        if not isinstance(task_id, int):
+            return None
+
+        if text:
+            lines = [
+                f"\n   ├─ Task #{task_id}",
+                f'\n   └─ "{truncate(text, 80)}"',
+            ]
+            return "".join(lines)
+
+        return f"\n   └─ Task #{task_id}"
+
+
+class FileMemoryToolFormatter(ToolCallFormatter):
+    """Formats FileMemory_* tool calls, showing file names and search patterns
+    with tree-view corners for save operations.
+    """
+
+    def can_format(self, call: Content) -> bool:
+        """Match FileMemory_* tool calls."""
+        return call.name is not None and call.name.startswith("FileMemory_")
+
+    def format_detail(self, call: Content) -> str | None:
+        """Format based on the specific FileMemory operation."""
+        if call.name == "FileMemory_SaveFile":
+            return self._format_save_file(call)
+        if call.name in ("FileMemory_ReadFile", "FileMemory_DeleteFile"):
+            value = get_argument_value(call, "fileName")
+            return f"({value})" if value else None
+        if call.name == "FileMemory_SearchFiles":
+            return self._format_search_files(call)
+        return None
+
+    def _format_save_file(self, call: Content) -> str | None:
+        """Format SaveFile with file name and description indicator."""
+        file_name = get_argument_value(call, "fileName")
+        description = get_argument_value(call, "description")
+
+        if not file_name:
+            return None
+
+        if description:
+            return f"\n   └─ {file_name} (with description)"
+        return f"\n   └─ {file_name}"
+
+    def _format_search_files(self, call: Content) -> str | None:
+        """Format SearchFiles with regex pattern and optional file pattern."""
+        pattern = get_argument_value(call, "regexPattern")
+        file_pattern = get_argument_value(call, "filePattern")
+
+        if not pattern:
+            return None
+
+        if file_pattern:
+            return f"(/{pattern}/ in {file_pattern})"
+        return f"(/{pattern}/)"
+
+
+# endregion
+
+# region Public API Functions
+
+
+def format_tool_call(formatters: list[ToolCallFormatter], call: Content) -> str:
+    """Format a tool call using the first matching formatter from the provided list.
+
+    Returns "{toolName} {detail}" when a formatter produces detail,
+    or just "{toolName}" otherwise.
+
+    Args:
+        formatters: List of formatters to try in order.
+        call: The function call content to format.
+
+    Returns:
+        Formatted string representation of the tool call.
+    """
+    for formatter in formatters:
+        if formatter.can_format(call):
+            detail = formatter.format_detail(call)
+            tool_name = call.name or "Unknown"
+            return f"{tool_name} {detail}" if detail is not None else tool_name
+
+    return call.name or "Unknown"
+
+
+def build_default_formatters() -> list[ToolCallFormatter]:
+    """Create the default list of tool call formatters.
+
+    The FallbackToolFormatter is always last. Users can call this function
+    and combine the result with their own formatters.
+
+    Returns:
+        A list of all built-in tool call formatters.
+    """
+    return [
+        TodoToolFormatter(),
+        ModeToolFormatter(),
+        BackgroundAgentToolFormatter(),
+        FileMemoryToolFormatter(),
+        WebSearchToolFormatter(),
+        FallbackToolFormatter(),
+    ]
+
+
+# endregion

python/samples/02-agents/harness/console/harness_console.py

@@ -0,0 +1,87 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""Main entry point for the harness console.
+
+Provides the top-level run_agent_async() function that creates and runs
+the Textual-based harness console application.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from .app import HarnessApp
+from .observers import build_default_observers
+
+if TYPE_CHECKING:
+    from agent_framework import Agent, AgentSession
+
+    from .commands import CommandHandler
+    from .observers.base import ConsoleObserver
+
+
+async def run_agent_async(
+    agent: Agent,
+    *,
+    session: AgentSession | None = None,
+    observers: list[ConsoleObserver] | None = None,
+    command_handlers: list[CommandHandler] | None = None,
+    mode_colors: dict[str, str] | None = None,
+    initial_mode: str | None = None,
+    placeholder: str = "Type a message and press Enter...",
+    title: str = "Harness Console",
+    max_context_window_tokens: int | None = None,
+    max_output_tokens: int | None = None,
+) -> None:
+    """Run the harness console with the given agent.
+
+    This is the main entry point for the harness console. Creates a Textual
+    application with the configured observers and runs it until the user exits.
+
+    Args:
+        agent: The agent to run conversations with.
+        session: Optional agent session for conversation history.
+        observers: List of console observers. If None, uses defaults.
+        command_handlers: List of command handlers. If None, auto-detected from agent.
+        mode_colors: Mapping of mode names to Rich color strings.
+        initial_mode: Initial agent mode text.
+        placeholder: Input placeholder text.
+        title: Application title.
+        max_context_window_tokens: Optional max context window size for usage display.
+        max_output_tokens: Optional max output tokens for usage display.
+
+    Example:
+        .. code-block:: python
+
+            from agent_framework import Agent
+            from agent_framework.openai import OpenAIChatClient
+            from console import run_agent_async
+
+            agent = Agent(
+                client=OpenAIChatClient(),
+                instructions="You are helpful.",
+            )
+
+            await run_agent_async(agent)
+    """
+    resolved_observers = observers or build_default_observers()
+    resolved_mode_colors = mode_colors or {
+        "plan": "cyan",
+        "execute": "green",
+    }
+    resolved_session = session or agent.create_session()
+
+    app = HarnessApp(
+        agent=agent,
+        observers=resolved_observers,
+        session=resolved_session,
+        mode_colors=resolved_mode_colors,
+        initial_mode=initial_mode,
+        placeholder=placeholder,
+        title=title,
+        max_context_window_tokens=max_context_window_tokens,
+        max_output_tokens=max_output_tokens,
+        command_handlers=command_handlers,
+    )
+
+    await app.run_async()

python/samples/02-agents/harness/console/observers/__init__.py

@@ -0,0 +1,122 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""Console observers for agent streaming lifecycle.
+
+This module provides observers that display events during agent streaming
+and collect follow-up actions. All observers use the IUXStateDriver interface
+to update the UI.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from .base import ConsoleObserver
+from .error_display import ErrorDisplayObserver
+from .planning_output import PlanningOutputObserver
+from .reasoning_display import ReasoningDisplayObserver
+from .text_output import TextOutputObserver
+from .tool_approval import ToolApprovalObserver
+from .tool_call_display import ToolCallDisplayObserver
+from .usage_display import UsageDisplayObserver
+
+if TYPE_CHECKING:
+    from agent_framework import Agent
+
+
+def build_default_observers() -> list[ConsoleObserver]:
+    """Build the default set of observers for the harness console.
+
+    Returns a standard observer list covering:
+    - Text output (streaming text display)
+    - Tool call display (formatted tool invocations)
+    - Error display (error messages)
+    - Usage display (token counts)
+    - Reasoning display (reasoning/thinking blocks)
+    - Tool approval (user approval for tool calls)
+
+    Note: PlanningOutputObserver is NOT included here because it requires
+    a mode_provider. Use build_observers_with_planning() for agents that
+    have an AgentModeProvider (i.e. agents created with create_harness_agent).
+
+    Returns:
+        List of default console observers.
+    """
+    return [
+        TextOutputObserver(),
+        ToolCallDisplayObserver(),
+        ErrorDisplayObserver(),
+        UsageDisplayObserver(),
+        ReasoningDisplayObserver(),
+        ToolApprovalObserver(),
+    ]
+
+
+def build_observers_with_planning(
+    agent: Agent,
+    plan_mode_name: str = "plan",
+    execution_mode_name: str = "execute",
+    *,
+    mode_colors: dict[str, str] | None = None,
+) -> list[ConsoleObserver]:
+    """Build observers with planning support (structured output in plan mode).
+
+    Replaces TextOutputObserver with PlanningOutputObserver, which configures
+    structured JSON output via response_format when in plan mode. This enables
+    the list picker UI for clarification and approval questions.
+
+    Requires that the agent has an AgentModeProvider in its context_providers
+    (automatically added by create_harness_agent).
+
+    Args:
+        agent: The agent to resolve the AgentModeProvider from.
+        plan_mode_name: The mode name that represents planning mode.
+        execution_mode_name: The mode name to switch to on approval.
+        mode_colors: Optional mapping of mode names to Rich color strings.
+
+    Returns:
+        List of observers with planning support.
+
+    Raises:
+        ValueError: If the agent has no AgentModeProvider.
+    """
+    from agent_framework import AgentModeProvider
+
+    mode_provider = next(
+        (p for p in agent.context_providers if isinstance(p, AgentModeProvider)),
+        None,
+    )
+    if mode_provider is None:
+        msg = (
+            "Planning observers require an AgentModeProvider on the agent. "
+            "Use create_harness_agent() or add AgentModeProvider to context_providers."
+        )
+        raise ValueError(msg)
+
+    return [
+        ToolCallDisplayObserver(),
+        ToolApprovalObserver(),
+        ErrorDisplayObserver(),
+        ReasoningDisplayObserver(),
+        UsageDisplayObserver(),
+        PlanningOutputObserver(
+            mode_provider,
+            plan_mode_name,
+            execution_mode_name,
+            mode_colors=mode_colors,
+        ),
+    ]
+
+
+__all__ = [
+    "ConsoleObserver",
+    "ErrorDisplayObserver",
+    "PlanningOutputObserver",
+    "ReasoningDisplayObserver",
+    "TextOutputObserver",
+    "ToolApprovalObserver",
+    "ToolCallDisplayObserver",
+    "UsageDisplayObserver",
+    "build_default_observers",
+    "build_observers_with_planning",
+]